openapi: 3.0.3
info:
  title: Project Ham API Specification
  version: 0.0.1
  contact:
    name: Project Maintainer
    email: me@hamzantal.pw
  license:
    name: MIT
paths:
  /auth/login:
    post:
      tags:
        - Auth Endpoints
      summary: Attemps to log in a user with credentials, and returns an access token.
      requestBody:
        $ref: '#/components/requestBodies/AuthCredentials'
      responses:
        200:
          description: You have been successfully logged in, and you can use the token to interact with the web server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        400:
          $ref: '#/components/responses/MalformedBody'
        401:
          $ref:  '#/components/responses/InvalidCredentials'
        500:
          $ref: '#/components/responses/ServerError'

components:
  requestBodies:
    AuthCredentials:
      description: User credentials.
      required: true
      content:
        application/json:
          schema:
            required:
              - username
              - password
            type: object
            properties:
              username:
                type: string
                description: The username of the user.
              password:
                type: string
                description: The password of the user.
  responses:
    MalformedBody:
      description: The information in your body is incomplete, or your JSON format is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            reason: Invalid request body provided.
            code: 400
    InvalidCredentials:
      description: The credentials you have provided are incorrect.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            reason: The username or password provided are incorrect.
            code: 401
    ServerError:
      description: The server could not complete a request due to an unknown error. More informatino may be available in the description.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            reason: The internal server reached an unknown state.
            code: 500
  schemas:
    Token:
      required:
        - token
      type: object
      properties:
        token:
          type: string
          description: The access token value
    Error:
      required:
        - reason
        - code
      type: object
      properties:
        reason:
          type: string
          description: The cause of the error message
        code:
          type: integer
          description: The HTTP error code value accompanying the error.