Petstore API: The Classic OpenAPI Example

The Petstore API Specification

The Petstore API is the canonical example used throughout the OpenAPI ecosystem. Originally created by the Swagger team, it demonstrates all core concepts of the OpenAPI specification in a simple, understandable context — managing pets in a pet store.

Document Structure

Every OpenAPI 3.0 document starts with three required sections:

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

• openapi — The specification version (3.0.x or 3.1.x)
• info — Metadata including title, description, version, and contact
• paths — The available endpoints and their operations

Endpoints

The Petstore typically defines these operations:

Method	Path	Description
GET	/pets	List all pets with optional limit
POST	/pets	Create a new pet
GET	/pets/{petId}	Get a specific pet by ID
DELETE	/pets/{petId}	Delete a specific pet

Schemas

The components/schemas section defines reusable data models:

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

Schemas are referenced using $ref: "#/components/schemas/Pet" throughout the paths section, keeping the document DRY and maintainable.

Why Start with Petstore

The Petstore demonstrates all fundamental OpenAPI patterns in approximately 100 lines of YAML. It covers path parameters, query parameters, request bodies, multiple response codes, schema references, and component reuse. Most OpenAPI tutorials and tool documentation use it as the starting point.