openapi-3.1.0.yaml

openapi: 3.1.0
info:
  title: Pet Store API
  description: A sample API for managing pets in a store
  termsOfService: https://example.com/terms/
  contact:
    name: API Support
    url: https://example.com/support
    email: support@example.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging-api.example.com/v1
    description: Staging server
  - url: https://dev-api.example.com/v1
    description: Development server

paths:
  /pets:
    get:
      summary: List all pets
      description: Returns all pets from the system
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: Maximum number of pets to return
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 20
        - name: status
          in: query
          description: Status of pets to return
          required: false
          schema:
            type: string
            enum: [available, pending, sold]
      responses:
        '200':
          description: A list of pets
          content:
            application/json:
              schema:
                type: object
                required:
                  - pets
                properties:
                  pets:
                    type: array
                    items:
                      $ref: '#/components/schemas/Pet'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              examples:
                listExample:
                  summary: Example pet list
                  value:
                    pets:
                      - id: 1
                        name: Fluffy
                        status: available
                        category: 
                          id: 1
                          name: Cat
                      - id: 2
                        name: Rex
                        status: sold
                        category:
                          id: 2
                          name: Dog
                    pagination:
                      totalCount: 50
                      pageSize: 20
                      currentPage: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - apiKey: []
        - oauth2: [readpets]
        
    post:
      summary: Create a pet
      description: Creates a new pet in the store
      operationId: createPet
      tags:
        - pets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewPet'
            examples:
              newPet:
                summary: Example of new pet
                value:
                  name: Fluffy
                  status: available
                  category:
                    name: Cat
      responses:
        '201':
          description: Successfully created pet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - apiKey: []
        - oauth2: [writepets]

  /pets/{petId}:
    parameters:
      - name: petId
        in: path
        description: ID of pet to fetch
        required: true
        schema:
          type: integer
          format: int64
          minimum: 1
    get:
      summary: Get pet by ID
      description: Returns a single pet by ID
      operationId: getPet
      tags:
        - pets
      responses:
        '200':
          description: Pet details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - apiKey: []
        - oauth2: [readpets]

    put:
      summary: Update pet
      description: Updates an existing pet
      operationId: updatePet
      tags:
        - pets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
      responses:
        '200':
          description: Successfully updated pet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - apiKey: []
        - oauth2: [writepets]
    
    delete:
      summary: Delete pet
      description: Deletes a pet by ID
      operationId: deletePet
      tags:
        - pets
      responses:
        '204':
          description: Pet successfully deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - apiKey: []
        - oauth2: [writepets]

components:
  schemas:
    Category:
      type: object
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 50
      required:
        - name

    Pet:
      type: object
      required:
        - id
        - name
        - status
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 100
        status:
          type: string
          enum:
            - available
            - pending
            - sold
          default: available
        category:
          $ref: '#/components/schemas/Category'
        tags:
          type: array
          items:
            type: string
        photoUrls:
          type: array
          items:
            type: string
            format: uri
        metadata:
          type: object
          additionalProperties: true

    NewPet:
      type: object
      required:
        - name
        - status
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        status:
          type: string
          enum:
            - available
            - pending
            - sold
          default: available
        category:
          $ref: '#/components/schemas/Category'
        tags:
          type: array
          items:
            type: string
        photoUrls:
          type: array
          items:
            type: string
            format: uri
        metadata:
          type: object
          additionalProperties: true

    Pagination:
      type: object
      properties:
        totalCount:
          type: integer
          format: int32
          minimum: 0
        pageSize:
          type: integer
          format: int32
          minimum: 1
        currentPage:
          type: integer
          format: int32
          minimum: 1
        totalPages:
          type: integer
          format: int32
          minimum: 0

    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            type: string

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 400
            message: Bad request
            details:
              - "Invalid value for parameter 'limit'"

    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 401
            message: Unauthorized
            details:
              - "Authentication credentials are missing or invalid"

    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 403
            message: Forbidden
            details:
              - "You don't have permission to access this resource"

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 404
            message: Not found
            details:
              - "The requested resource was not found"

    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 500
            message: Internal server error
            details:
              - "An unexpected error occurred"
              
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-API-Key
      in: header
      description: API key for authentication
    oauth2:
      type: oauth2
      description: OAuth2 authentication
      flows:
        implicit:
          authorizationUrl: https://auth.example.com/authorize
          scopes:
            read:pets: Read access to pets
            write:pets: Write access to pets
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          scopes:
            readpets: Read access to pets
            writepets: Write access to pets

tags:
  - name: pets
    description: Pet operations

externalDocs:
  description: Find more info here
  url: https://example.com/docs