swagger.yml

swagger: '2.0'
info:
  version: 1.0.0
  title: My Service API
  description: '#### Returns some information'
schemes:
  - http
host: myhost.net
basePath: /
paths:
  /mycat:
    get:
      parameters:
        - name: id
          in: query
          description: mycat id
          required: true
          type: integer
          format: int32
        - name: x-api-key
          in: header
          description: client api key
          required: true
          type: string
      summary: returns cat info
      description: this endpoint returns cats info
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Cat'
        '400':
          description: Cat id missing or not a string
          schema:
            $ref: '#/definitions/errorResponse'
        '404':
          description: Cat not found
          schema:
            $ref: '#/definitions/errorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/errorResponse'
definitions:
  errorResponse:
    type: object
    properties:
      errorMessage:
        type: string
  Cat:
    type: object
    properties:
      name:
        type: string
      type:
        type: string
    required:
      - name
      - type