Petstore API：定番のOpenAPIサンプル

Petstore API仕様

Petstore APIはOpenAPIエコシステム全体で使用される定番のサンプルです。元々Swaggerチームによって作成され、ペットショップのペット管理というシンプルで理解しやすいコンテキストで、OpenAPI仕様のすべてのコア概念を示しています。

ドキュメント構造

すべてのOpenAPI 3.0ドキュメントは3つの必須セクションから始まります：

openapi: "3.0.3"
info:
  title: Petstore API
  version: "1.0.0"
paths:
  /pets:
    get:
      summary: List all pets

• openapi — 仕様バージョン（3.0.xまたは3.1.x）
• info — タイトル、説明、バージョン、連絡先を含むメタデータ
• paths — 利用可能なエンドポイントとその操作

エンドポイント

Petstoreは通常これらの操作を定義します：

メソッド	パス	説明
GET	/pets	オプションのlimit付きで全ペットを一覧表示
POST	/pets	新しいペットを作成
GET	/pets/{petId}	IDでペットを取得
DELETE	/pets/{petId}	ペットを削除

スキーマ

components/schemas セクションは再利用可能なデータモデルを定義します：

components:
  schemas:
    Pet:
      type: object
      required: [id, name]
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string

スキーマはpathsセクション全体で $ref: "#/components/schemas/Pet" を使用して参照され、ドキュメントをDRYでメンテナンスしやすく保ちます。

なぜPetstoreから始めるのか

Petstoreは約100行のYAMLですべての基本的なOpenAPIパターンを示しています。パスパラメータ、クエリパラメータ、リクエストボディ、複数のレスポンスコード、スキーマ参照、コンポーネントの再利用をカバーしています。ほとんどのOpenAPIチュートリアルやツールのドキュメントがこれを出発点として使用しています。