openapi: 3.0.1
security:
  - basicAuth: []
info:
  title: Whiskey API
  description: |
    ## Whiskey API

    This is the whiskey API provided by Hungovercoders.

    ![Hungovercoders](https://www.hungovercoders.com/assets/logo3.ico)

    These are the services levels available:

    ```mermaid
        sequenceDiagram
          Alice->>+John: Hello John, how are you?
          Alice->>+John: John, can you hear me?
          John->-Alice: Hi Alice, I can hear you!
          John->-Alice: I feel great!
    ```
  version: "0.0"
tags:
  - name: whiskey
    description: Whiskey operations
servers:
  - url: https://api.example.com/v1
    description: Production server (uses live data)
  - url: https://sandbox-api.example.com:8443/v1
    description: Sandbox server (uses test data)
paths:
  /whiskeys:
    get:
      summary: Get all whiskeys
      operationId: getAllWhiskeys
      tags:
        - whiskey
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                maxItems: 100
                items:
                  $ref: '#/components/schemas/Whiskey'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Server Error
    post:
      summary: Add a new whiskey
      operationId: addWhiskey
      tags:
        - whiskey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Whiskey'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Whiskey'
          links:
            GetWhiskey:
              operationId: getAWhiskey
              parameters:
                id: $response.body#/id
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Invalid input
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Server Error
  /whiskeys/{id}:
    get:
      summary: Get a specific whiskey
      operationId: getAWhiskey
      tags: 
        - whiskey
      parameters:
        - name: id
          in: path
          description: The ID of the whiskey to retrieve
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Whiskey'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Invalid ID supplied
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Whiskey not found
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Server Error
        default:
          description: Non-specific HTTP response code
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      summary: Delete a specific whiskey
      operationId: deleteAWhiskey
      tags:
        - whiskey
      parameters:
        - name: id
          in: path
          description: The ID of the whiskey to delete
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Invalid ID supplied
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Whiskey not found
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Server Error
        default:
          description: Non-specific HTTP response code
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  schemas:
    Whiskey:
      x-tags:
        - whiskey
      title: Whiskey
      description: A whiskey object
      type: object
      properties:
        id:
          type: string
        name:
          type: string
          minLength: 1
          maxLength: 50
        age:
          type: integer
          format: int32
          minimum: 3
          maximum: 200
        abv:
          type: number
          format: percent
          minimum: 0
          maximum: 92
        distillery:
          type: string
          minLength: 1
          maxLength: 50
        type: 
          type: string
          enum:
            - Single Malt
            - Blended
            - Bourbon
            - Rye
            - Corn
            - Wheat
            - Other
        country:
          type: string
          enum:
            - Scotland
            - Ireland
            - USA
            - Canada
            - Japan
            - Wales
            - England
            - India
            - Australia
            - Other
      additionalProperties: false
    Error:
        type: object
        required:
          - code
        properties:
          code:
            type: integer
            format: int32
          message:
            type: string
  securitySchemes:
    apiKey:
      description: API Key
      type: apiKey
      name: api-key
      in: header
    basicAuth:
      description: Basic Authentication
      type: http
      scheme: basic