catbreeds.yaml

openapi: 3.0.3
info:
  title: Cat Breeds API
  description: Simple API to manage a collection of cat breeds.
  version: 1.1.0
servers:
  - url: https://api.cats.com/v1

# 🔐 Global security: every operation requires X-API-Token
security:
  - ApiTokenAuth: []

paths:
  /breeds:
    get:
      summary: Get list of cat breeds
      operationId: getBreeds
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paginated list of cat breeds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedCatBreeds'
              examples:
                page1:
                  summary: First page example
                  value:
                    page: 1
                    pageSize: 20
                    total: 53
                    totalPages: 3
                    items:
                      - id: "bengal-1234"
                        name: "Bengal"
                        origin: "Asia"
                        description: "The Bengal cat has a wild appearance with large spots and rosettes."
                      - id: "siamese-5678"
                        name: "Siamese"
                        origin: "Thailand"
                        description: "The Siamese is one of the first distinctly recognized breeds of Asian cats."
    post:
      summary: Add a new cat breed
      operationId: addBreed
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CatBreedInput'
      responses:
        '201':
          description: Cat breed created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatBreed'

  /breeds/{id}:
    get:
      summary: Fetch a specific cat breed by ID
      operationId: getBreedById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single cat breed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatBreed'
        '404':
          description: Cat breed not found
    put:
      summary: Update a cat breed
      operationId: updateBreed
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CatBreedInput'
      responses:
        '200':
          description: Cat breed updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatBreed'
        '404':
          description: Cat breed not found
    delete:
      summary: Delete a cat breed
      operationId: deleteBreed
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Cat breed deleted
        '404':
          description: Cat breed not found

components:
  securitySchemes:
    ApiTokenAuth:
      type: apiKey
      in: header
      name: X-API-Token
      description: |
        Provide your API token in the `X-API-Token` header, e.g.
        `X-API-Token: <your-token>`

  parameters:
    Page:
      name: page
      in: query
      description: 1-based page index.
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
    PageSize:
      name: pageSize
      in: query
      description: Number of items per page.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20

  schemas:
    PaginatedCatBreeds:
      type: object
      properties:
        page:
          type: integer
          example: 1
        pageSize:
          type: integer
          example: 20
        total:
          type: integer
          example: 53
        totalPages:
          type: integer
          example: 3
        items:
          type: array
          items:
            $ref: '#/components/schemas/CatBreed'
      required: [page, pageSize, total, totalPages, items]

    CatBreed:
      type: object
      properties:
        id:
          type: string
          example: "bengal-1234"
        name:
          type: string
          example: "Bengal"
        origin:
          type: string
          example: "Asia"
        description:
          type: string
          example: "The Bengal cat has a wild appearance with large spots and rosettes."
      required: [id, name]

    CatBreedInput:
      type: object
      properties:
        name:
          type: string
          example: "Siamese"
        origin:
          type: string
          example: "Thailand"
        description:
          type: string
          example: "The Siamese is one of the first distinctly recognized breeds of Asian cats."
      required: [name]