gitbook-petstore.yaml

openapi: 3.0.3
info:
  title: GitBook Petstore API
  version: 1.0.0
  description: |
    ## Petstore

    Welcome to the Petstore API Documentation Template! This is a starting point for creating clear, interactive, and user-friendly API documentation. 

    Use this template to explore best practices in structuring your docs, showcasing endpoints, and guiding users through your API. Everything here can be adapted to fit your own product.

    {% hint style="info" %}
    **Why this demo?**  
    This template shows automatically generated docs from an OpenAPI spec. It uses [Gitbook-specific Open API extensions](https://gitbook.com/docs/extensions-reference) to create a rich, interactive experience.
    {% endhint %}

    {% tabs %}
    {% tab title="Production" %}
    **Base URL**  
    `https://petstore.example.com/v1`
    {% endtab %}

    {% tab title="Staging" %}
    **Base URL**  
    `https://staging.petstore.example.com/v1`
    {% endtab %}
    {% endtabs %}

    ### Getting Started
    {% stepper %}
    {% step %}
    ### Create an account
    Sign up for a free account at [petstore.example.com](https://petstore.example.com).
    {% endstep %}
    {% step %}
    ### Get your API key 
    Sign in to the Petstore console and copy your key.
    {% endstep %}
    {% step %}
    ### Make your first request
    Call the GET /pets endpoint to check connectivity.
    {% endstep %}
    {% endstepper %}

    ### Learn more
    <table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Documentation</strong></td><td>Everything you need to know about the product</td><td></td><td></td><td></td></tr><tr><td><strong>Changelog</strong></td><td>See what’s new and improved</td><td></td><td></td><td></td></tr><tr><td><strong>Community</strong></td><td>Connect with other users and contributors</td><td></td><td></td><td></td></tr></tbody></table>

    {% hint style="warning" %}
    This API is for demo purposes only — **don’t** use it in production.
    {% endhint %}

servers:
  - url: https://petstore.example.com/v1

# ───────────────────────────────── TAGS ─────────────────────────────────
tags:
  - name: store
    x-page-title: Store
    x-page-description: Manage customer orders
    x-page-icon: store
  - name: pets
    x-parent: store
    x-page-title: Pets
    x-page-description: Everything about your pets
    x-page-icon: paw
  - name: admin
    x-page-title: Admin
    x-page-description: Internal administration endpoints
    x-page-icon: shield-cat

# ──────────────────────────────── PATHS ─────────────────────────────────
paths:
  /pets:
    get:
      summary: List all pets
      tags: [pets]
      operationId: listPets
      parameters:
        - name: limit
          in: query
          description: Max items to return (100 default)
          schema: { type: integer, maximum: 100 }
      responses:
        "200":
          description: A paged array of pets
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Pets" }
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -L https://petstore.example.com/v1/pets
        - lang: JavaScript
          label: Fetch
          source: |
            fetch('https://petstore.example.com/v1/pets')
              .then(r => r.json())
              .then(console.log)

    post:
      summary: Create a pet
      tags: [pets]
      operationId: createPets
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/Pet" }
      responses:
        "201": { description: Pet created }
      x-stability: experimental

  /pets/{petId}:
    get:
      summary: Info for a specific pet
      tags: [pets]
      operationId: showPetById
      parameters:
        - name: petId
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Pet response
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Pet" }
      deprecated: true
      x-deprecated-sunset: 2030-12-05

  /store/orders:
    get:
      summary: List store orders
      tags: [store]
      operationId: listOrders
      responses:
        "200":
          description: Array of orders
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Order" }
      x-hideTryItPanel: true

  /internal/metrics:
    get:
      summary: Platform metrics (internal use only)
      tags: [admin]
      operationId: getMetrics
      responses:
        "200": { description: OK }
      x-internal: true

# ───────────────────────────── COMPONENTS ──────────────────────────────
components:
  schemas:
    PetStatus:
      type: string
      enum: [available, pending, sold]
      x-enumDescriptions:
        available: Pet is available for adoption
        pending: Awaiting adoption
        sold: No longer available
    Pet:
      type: object
      required: [id, name]
      properties:
        id: { type: integer, format: int64, example: 1 }
        name: { type: string, example: Fluffy }
        tag: { type: string, example: dog }
        status: { $ref: "#/components/schemas/PetStatus" }
    Pets:
      type: array
      items: { $ref: "#/components/schemas/Pet" }
    Order:
      type: object
      properties:
        id: { type: integer, format: int64 }
        petId: { type: integer, format: int64 }
        quantity: { type: integer }
        shipDate: { type: string, format: date-time }
        complete: { type: boolean }