mareshq-yggdrasil/api/v1/openapi.yaml

openapi: "3.1.0"
info:
  version: "0.1.0"
  title: MaresHQ API
  license:
    name: Proprietary
  contact:
    name: Vojtěch Mareš
    email: iam@vojtechmares.com
    url: https://www.vojtechmares.com

servers:
  - url: http://localhost:3000
    description: Local development server

tags:
  - name: Trainings
    description: Operations about trainings

paths:
  /v1/trainings:
    get:
      summary: List all trainings
      operationId: listTrainings
      tags:
        - Trainings
      responses:
        "200":
          description: A list of trainings
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListTrainingsResponse"
        "500":
          $ref: "#/components/responses/InternalError"

    post:
      summary: Create a new training
      operationId: createTraining
      tags:
        - Trainings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateTrainingRequest"
      responses:
        "201":
          description: Training created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateTrainingResponse"
        "400":
          $ref: "#/components/responses/InvalidInputError"
        "500":
          $ref: "#/components/responses/InternalError"

  /v1/trainings/{trainingID}:
    get:
      summary: Get a training by ID
      operationId: getTraining
      tags:
        - Trainings
      parameters:
        - $ref: "#/components/parameters/TrainingID"
      responses:
        "200":
          description: A training
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetTrainingResponse"
        "404":
          $ref: "#/components/responses/NotFoundError"

        "500":
          $ref: "#/components/responses/InternalError"

    put:
      summary: Update a training by ID
      operationId: updateTraining
      tags:
        - Trainings
      parameters:
        - $ref: "#/components/parameters/TrainingID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateTrainingRequest"
      responses:
        "200":
          description: Training updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UpdateTrainingResponse"
        "400":
          $ref: "#/components/responses/InvalidInputError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"

    delete:
      summary: Delete a training by ID
      operationId: deleteTraining
      tags:
        - Trainings
      parameters:
        - $ref: "#/components/parameters/TrainingID"
      responses:
        "204":
          description: Training deleted
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"

components:
  parameters:
    TrainingID:
      in: path
      name: trainingID
      required: true
      schema:
        $ref: "#/components/schemas/TrainingID"
      description: Training ID

  schemas:
    CreateTrainingRequest:
      $ref: "#/components/schemas/NewTraining"

    CreateTrainingResponse:
      $ref: "#/components/schemas/Training"

    ListTrainingsResponse:
      type: array
      items:
        $ref: "#/components/schemas/Training"

    GetTrainingResponse:
      $ref: "#/components/schemas/Training"

    UpdateTrainingRequest:
      $ref: "#/components/schemas/NewTraining"

    UpdateTrainingResponse:
      $ref: "#/components/schemas/Training"

    NewTraining:
      type: object
      properties:
        name:
          type: string
        days:
          type: integer
          format: int8
          minimum: 1
          maximum: 5
        description:
          type: string
      required:
        - name
        - days
        - description

    Training:
      allOf:
        - $ref: "#/components/schemas/NewTraining"
        - type: object
          properties:
            id:
              $ref: "#/components/schemas/TrainingID"
          required:
            - id

    TrainingID:
      type: string
      format: uuid
      x-go-type: training.TrainingID
      x-go-type-import:
        path: gitlab.mareshq.com/hq/yggdrasil/pkg/training

    ProblemDetails:
      type: object
      description: >
        Schema that carries the details of an error in an HTTP response.
        See https://datatracker.ietf.org/doc/html/rfc7807 for more information.
      properties:
        type:
          type: string
          description: A URI reference that identifies the problem type.
        title:
          type: string
          description: A human-readable summary of the problem type.
        status:
          type: integer
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem.
      required:
        - type
        - title
        - status
        - detail
        - instance

  responses:
    InvalidInputError:
      description: Invalid input error
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ProblemDetails"

    InternalError:
      description: Internal error
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ProblemDetails"

    NotFoundError:
      description: Not found error
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ProblemDetails"