api.yaml

openapi: "3.0.0"
info:
  version: 0.0.1
  title: Akka Http Animal Service
paths:
  /animals:
    get:
      description: Returns all animals.
      responses:
        200:
          description: A successful response containing an array of animals.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AnimalResponseBody'
    post:
      description: Creates a new animal.
      requestBody:
        description: Animal to be created.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnimalRequestBody'
      responses:
        '201':
          description: Animal created response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnimalResponseBody'
        '400':
          description: |
            Bad request. For example, it can occur when request body is wrong, malformed, or headers are missing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
  /animals/{id}:
    get:
      description: Returns an animal by ID.
      parameters:
        - name: id
          in: path
          description: ID of an animal to fetch
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Animal response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnimalResponseBody'
        '400':
          description: Animal with given ID not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
    delete:
      description: Deletes a single animal by ID.
      parameters:
        - name: id
          in: path
          description: ID of an animal to delete.
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: Animal deleted.
components:
  schemas:
    AnimalRequestBody:
      required:
        - name
        - age
        - kind
      properties:
        name:
          type: string
        age:
          type: integer
        kind:
          type: string
      example: {
        "name": "Charlie",
        "age": 16,
        "kind": "Unicorn"
      }
    AnimalResponseBody:
      required:
        - id
        - name
        - age
        - kind
      properties:
        id:
          type: string
        name:
          type: string
        age:
          type: integer
        kind:
          type: string
      example: {
          "id": "abbf13",
          "name": "Charlie",
          "kind": "Unicorn",
          "age": 16
        }
    BadRequest:
      required:
        - message
      properties:
        message:
          type: string
      example: {
        "message": "Bad request."
      }
    NotFound:
      required:
        - message
      properties:
        message:
          type: string
      example: {
        "message": "Animal not found."
      }