Cat Management API for POST/CON 2019 workshop

api-v0.1.yaml

openapi: 3.0.0
info:
  title: Cat Management API
  version: '0.1'
  description: Hypothetical internal service API for managing database of cats in the household
servers:
  - url: 'https://api.cat'
    description: production
paths:
  /cats:
    get:
      summary: Get all cats
      description: Get all cats
      security:
        - apiKey: []
      responses:
        '200':
          description: Return list of all cats
          headers: {}
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Cat'
              examples:
                List of cats:
                  - id: 1
                    name: Munchkins
                    breed: Persian
                    age: 2
                  - id: 2
                    name: Peaches
                    breed: Bombay
                    age: 1
    post:
      summary: Add a new cat
      responses:
        '200':
          description: Cat created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
      description: Add a new cat
      security:
        - apiKey: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Cat'
            examples:
              New cat details:
                name: Munchkins
                breed: Persian
                age: 2
        description: "Cat's details"
components:
  schemas:
    Cat:
      title: Cat
      type: object
      description: Describes a Cat
      properties:
        id:
          type: integer
        name:
          type: string
        breed:
          type: string
        age:
          type: integer
      required:
        - name
        - breed
  securitySchemes:
    apiKey:
      name: X-API-KEY
      type: apiKey
      in: header
      description: API key to make requests to this service

api-v0.2.yaml

openapi: 3.0.0
info:
  title: Cat Management API
  version: '0.2'
  description: Hypothetical internal service API for managing database of cats in the household
servers:
  - url: 'https://api.cat'
    description: production
paths:
  /cats:
    get:
      summary: Get all cats
      description: Get all cats
      security:
        - apiKey: []
      responses:
        '200':
          description: Return list of all cats
          headers: {}
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Cat'
              examples:
                List of cats:
                  - id: 1
                    name: Munchkins
                    breed: Persian
                    age: 2
                  - id: 2
                    name: Peaches
                    breed: Bombay
                    age: 1
    post:
      summary: Add a new cat
      responses:
        '200':
          description: Cat created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
      description: Add a new cat
      security:
        - apiKey: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Cat'
            examples:
              New cat details:
                name: Munchkins
                breed: Persian
                age: 2
        description: "Cat's details"
 '/cat/{catId}':
    parameters:
      name: catId
      in: path
      required: true
      type: string
    get:
      summary: Find a cat by ID
      tags: []
      responses:
        '200':
          description: Found a cat
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cat'
              examples:
                Found cat:
                  id: 1337
                  name: Mojave
                  breed: Black Leopard
                  age: 4
      description: Find a cat by ID
      security:
        - apiKey: []
    
components:
  schemas:
    Cat:
      title: Cat
      type: object
      description: Describes a Cat
      properties:
        id:
          type: integer
        name:
          type: string
        breed:
          type: string
        age:
          type: integer
      required:
        - name
        - breed
  securitySchemes:
    apiKey:
      name: X-API-KEY
      type: apiKey
      in: header
      description: API key to make requests to this service