petstore.yaml

openapi: "3.0.0"
info:
  contact:
    name: John Doe
    url: http://some.url.info
    email: some.email@some.provider.net
  version: 1.0.0 # mandatory
  title: Swagger Petstore # mandatory
  description: |
    This is a sample API with educational purposes. 
    It's intended to show the right way to define an API using OAS3.
    Here you can see how to define endpoints, parameters, responses, etc. 
    You can also see usage examples to leverage all OpenApi posibilities. 
    Hope it profits you and your company.
    Enjoy.
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  # At least one is mandatory. You can define a server by environment
# Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/CloudAppi/swagger-petstore/1.0.0
  - url: http://swagger.io-sandbox/petstore-api/1.0.0 # URL is mandatory
    description: Sandbox server # It's absolutely recommended to describe the server 
  - url: http://swagger.io/petstore-api/1.0.0
    description: Production server
# All endpoints are defined here. The same path can include different operations. 
# Each path-operation pair is an endpoint
paths:
  /pets:
    get:
      summary: List all pets
      # Some common use cases for operationId are:
      #     Some code generators use this value to name the corresponding methods in code.
      #     Links can refer to the linked operations by operationId.
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: offset
          in: query
          description: Starting item index in collection.
          schema: 
            type: integer
            format: int32
            minimum: 0
            default: 0
            # Maximum value cannot be defined as the total number of pets is unknown.
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 10
      security:
        - OauthClientCredentials: []
        - OauthPassword:
          - reader
          - admin
      responses:
        '206':
          description: A paged array of pets
          headers:
            x-next:
              description: A link to the next page of responses
              schema:
                type: string
          content:
            application/json:    
              schema:
                $ref: "#/components/schemas/PetListResponse"
        '400': 
          $ref: "#/components/responses/BadRequest"
        '401':
          $ref: "#/components/responses/Unauthorized"
        default:
          $ref: '#/components/responses/DefaultError'
          
    post:
      summary: Create a pet
      operationId: createPets
      tags:
        - pets
      requestBody:
        $ref: '#/components/requestBodies/CreatePetRequestBody'
      security:
        - OauthPassword:
          - admin
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreatePetResponse"
        '400': 
          $ref: "#/components/responses/BadRequest"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"
        default:
          $ref: '#/components/responses/DefaultError'
          
  /pets/{petId}:
    get:
      summary: Info for a specific pet
      operationId: showPetById
      tags:
        - pets
      parameters:
        - $ref: '#/components/parameters/petId'
      security:
        - OauthClientCredentials: []
        - OauthPassword:
          - reader
          - admin
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetPetResponse"
        '400': 
          $ref: "#/components/responses/BadRequest"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '404':
          $ref: "#/components/responses/NotFound"
        default:
          $ref: '#/components/responses/DefaultError'
    put:
      summary: Update an specific pet
      operationId: updatePetById
      tags:
        - pets
      requestBody:
        $ref: '#/components/requestBodies/UpdatePetRequestBody'
      parameters:
        - $ref: '#/components/parameters/petId'
      security:
        - OauthPassword:
          - admin
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreatePetResponse"
        '400': 
          $ref: "#/components/responses/BadRequest"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"
        '404':
          $ref: "#/components/responses/NotFound"
        default:
          $ref: '#/components/responses/DefaultError'
    delete:
      summary: Delete an specific pet
      operationId: deletePetById
      tags:
        - pets
      parameters:
        - $ref: '#/components/parameters/petId'
      security:
        - OauthPassword:
          - admin
      responses:
        '204':
          $ref: "#/components/responses/NoContent"
        '400': 
          $ref: "#/components/responses/BadRequest"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '403':
          $ref: "#/components/responses/Forbidden"
        '404':
          $ref: "#/components/responses/NotFound"
        default:
          $ref: '#/components/responses/DefaultError'
# Here is where all reusable models, parameters, responses, request bodies, etc are defined          
components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
          example: Toby
        tag:
          type: string
          example: dog
    Pets:
      type: array
      items:
        $ref: "#/components/schemas/Pet"
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: Internal error code
          type: integer
          format: int32
        message:
          description: Error message
          type: string
    Errors:
      type: array
      items: 
        $ref: "#/components/schemas/Error"
          
    StandardResponse:
      type: object
      properties:
        result:
          type: boolean
          description: > 
            Operation result. _true_ if http code is 2xx, _false_ otherwise
          example: true
        http_code:
          type: integer
          format: int32
          description: Response http code.
          example: 200
        info:
          type: string
          description: Brief description of operation's result
          example: OK
      required:
        - result
        - http_code
        - info
        
    ErrorResponse:
      allOf: 
        - $ref: "#/components/schemas/StandardResponse"
      properties:
        errors:
          $ref: "#/components/schemas/Errors"
      required:
        - errors
          
    PetListResponse:
      allOf:
        - $ref: "#/components/schemas/StandardResponse"
      properties:
        data:
          type: object
          properties:
            pets:
              $ref: "#/components/schemas/Pets"
    
    CreatePetResponse:
      allOf:
        - $ref: "#/components/schemas/StandardResponse"
      properties:
        data:
          $ref: '#/components/schemas/Pet'
          
    GetPetResponse:
      allOf:
        - $ref: "#/components/schemas/StandardResponse"
      properties:
        data:
          $ref: '#/components/schemas/Pet'
  
  requestBodies:
    CreatePetRequestBody:
      description: A JSON object containing pet information
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                type: string
                minLength: 1
                maxLength: 50
                example: Kitty
              tag:
                type: string
                minLength: 1
                maxLength: 50
                example: cat
            required:
              - name
              
    UpdatePetRequestBody:
      description: A JSON object containing pet information
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                type: string
                minLength: 1
                maxLength: 50
                example: Kitty
              tag:
                type: string
                minLength: 1
                maxLength: 50
                example: cat

  parameters:
    petId:
      name: petId
      in: path
      required: true
      description: The id of the pet to retrieve
      schema:
        type: string
        minLength: 1
        maxLength: 25
        pattern: '[A-Za-z0-9]{1,25}'
              
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            allOf: 
              - $ref: "#/components/schemas/ErrorResponse"
          example:
            result: false
            http_code: 400
            info: parameter error
            errors:
              - code: 1
                message: Error on parameter x
                
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            allOf: 
              - $ref: "#/components/schemas/ErrorResponse"
          example:
            result: false
            http_code: 404
            info: Not Found
            errors:
              - code: 4
                message: Requested resource was not found

    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            allOf: 
              - $ref: "#/components/schemas/ErrorResponse"
          example:
            result: false
            http_code: 401
            info: Unauthorized
            errors:
              - code: 11
                message: User has not been authenticated

    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            allOf: 
              - $ref: "#/components/schemas/ErrorResponse"
          example:
            result: false
            http_code: 403
            info: Forbidden
            errors:
              - code: 12
                message: User has no permissions to access the resource 
                
    DefaultError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            allOf: 
              - $ref: "#/components/schemas/ErrorResponse"
          example:
            result: false
            http_code: 500
            info: Internal Server Error
            errors:
              - code: 10
                message: Unexpected server error
                
    NoContent:
      description: No content
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/StandardResponse'
          example:
            result: true
            http_code: 204
            info: No content
            
  securitySchemes:
      
    OauthClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://token.server/token
          refreshUrl: https://token.server/token
          scopes:
            reader: grants pet reading access
            admin: grants pet creation access
      
    OauthPassword:
      type: oauth2
      flows:
        password:
          tokenUrl: https://token.server/token
          refreshUrl: https://token.server/token
          scopes:
            reader: grants pet reading access
            admin: grants pet creation access