Swagger Petstore をお探しですか？

本当のアドレス

SmartBear の API ツールである Swagger は、Petstore の公開版を 2 つ運営しています。どちらもペット、注文、ユーザーという同じリソースを備えています。

新しいプロジェクトには Petstore 3 がおすすめです。現在のツールやコード ジェネレーターが前提とする OpenAPI 3.0 仕様に従っています。Swagger 2.0 版も引き続き応答し、古いチュートリアルに登場します。

試してみる

curl によるリクエスト例です。ベース URL を上のいずれかのアドレスに設定すれば、Postman、Insomnia、生成したクライアントでも同じパスが使えます。

# ステータスが "available" のペット
curl -H "Accept: application/json" "https://petstore3.swagger.io/api/v3/pet/findByStatus?status=available"

# ペットを追加（name と photoUrls は必須）
curl -X POST "https://petstore3.swagger.io/api/v3/pet" \
  -H "Content-Type: application/json" \
  -d '{"id": 12345, "name": "doggie", "photoUrls": [], "status": "available"}'

# ステータスごとの在庫（テスト用キー付き）
curl -H "api_key: special-key" "https://petstore.swagger.io/v2/store/inventory"

PHP からは、Guzzle を使って同じリクエストを送れます。

// PHP, Guzzle:ステータスが "available" のペット
$client = new GuzzleHttp\Client(['base_uri' => 'https://petstore3.swagger.io/api/v3/']);
$response = $client->get('pet/findByStatus', ['query' => ['status' => 'available']]);
$pets = json_decode((string) $response->getBody(), true);

主なパス: /pet、/pet/findByStatus、/pet/findByTags、/pet/{petId}、/store/inventory、/store/order、/user、/user/login、/user/logout。

キーとサインイン

Petstore は 2 つのセキュリティ方式を示しています。api_key ヘッダーによる API キーと、OAuth 2.0 フロー（petstore_auth）です。Swagger 2.0 の定義では、認可フィルターのテスト用キーとして special-key が示されています。これらはデモ用の認証情報です。本物のキー、トークン、パスワードを Petstore で試さないでください。

共有のテストデータ

全員が同じ公開サーバーを使っています。作成したデータは他の人が読み取り、変更、削除でき、findByStatus は他の人が追加したものを返します。奇妙な名前や壊れたレコードも含まれます。作成したばかりのペットがすでに消えていることもあります。

• 本物の個人データ、顧客データ、認証情報は絶対に送らないでください。
• 公開サーバーを前提に自動テストを組まないでください。結果は予測できず、応答が遅かったりエラー（500）を返したりすることがあります。
• 安定した結果が必要なら、自分のコピーを動かしましょう。

ローカルで実行する

Petstore はオープンソース（Apache 2.0）です。Docker ならコマンド 1 つで動きます。

docker run -d --name petstore -p 8080:8080 swaggerapi/petstore3

# Swagger UI:     http://localhost:8080
# API 定義:       http://localhost:8080/api/v3/openapi.json
# ベース URL:     http://localhost:8080/api/v3

Docker を使わない場合は、swagger-api/swagger-petstore をクローンして mvn package jetty:run で起動します（こちらもポート 8080）。自分のコピーは起動するたびに同じ組み込みのサンプル データ（ペット 10 匹と、いくつかの注文とユーザー）で始まるため、テストは毎回同じように動作します。

動かない v1 のアドレス

OpenAPI 仕様のリポジトリにあるサンプル ファイル petstore.yaml は、サーバーとして http://petstore.swagger.io/v1、パスとして /pets を記載しています。このファイルは仕様を説明するためのもので、背後にサービスはありません。このファイルから生成したクライアントは 404 Not Found を受け取ります。https://petstore3.swagger.io/api/v3 または自分のコピーを指定してください。パスが異なる（/pets ではなく /pet）ため、Petstore 3 の openapi.json からクライアントを生成し直してください。

ここにたどり着いた場合

example-petstore.com は別の名前で、Google のアナリティクスと検索に関するドキュメントに出てくるサンプル ドメインです。API はありません。このドメインの /v2/pet のようなパスへのリクエストには、JSON の説明付きで 410 Gone が返ります。

• コード、.env ファイル、Postman の環境、OpenAPI 定義の servers フィールドにあるベース URL を確認し、example-petstore.com を上のいずれかのアドレスに置き換えてください。
• それらのリクエストに本物のキーやトークンが含まれていましたか？ 漏えいしたものとして扱ってください: 漏えいした認証情報: 今すぐ行うべきこと
• ベース URL を設定で管理する方法: API クライアントと SDK の設定

関連ガイド

出典

• swagger-api/swagger-petstore GitHub
• Swagger Petstore (OpenAPI 3.0) Swagger
• Swagger Petstore (Swagger 2.0) Swagger
• swaggerapi/petstore3 Docker Hub
• OpenAPI Specification example petstore.yaml OpenAPI Initiative