mareshq-backoffice-v3-api/api/openapi.yaml

openapi: "3.0.3"
info:
  title: "Backoffice API"
  version: "0.2.0"
  license:
    name: Proprietary
  contact:
    name: Vojtěch Mareš
    email: vojtech@mares.cz
    url: https://www.mares.cz
servers:
  - url: http://localhost:8080/
    description: Local development server
  - url: https://staging.backoffice.vmdevel.cz/api
    description: Backoffice staging server
  - url: https://backoffice.mareshq.com/api
    description: Backoffice production server
paths:
  /v0/trainings:
    get:
      summary: List all trainings
      operationId: listTrainings
      tags:
        - Trainings
      responses:
        "200":
          $ref: "#/components/responses/ListTrainingsResponse"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      summary: Create a new training
      operationId: createTraining
      tags:
        - Trainings
      requestBody:
        $ref: "#/components/requestBodies/CreateTrainingRequest"
      responses:
        "201":
          $ref: "#/components/responses/CreateTrainingResponse"
        "400":
          $ref: "#/components/responses/InvalidInputError"
        "500":
          $ref: "#/components/responses/InternalError"
  /v0/trainings/{trainingID}:
    get:
      summary: Get a training by ID
      operationId: getTrainingByID
      tags:
        - Trainings
      parameters:
        - $ref: "#/components/parameters/TrainingID"
      responses:
        "200":
          $ref: "#/components/responses/GetTrainingResponse"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"
  /v0/trainings/{trainingID}/publish:
    put:
      summary: Publish a training
      operationId: publishTraining
      tags:
        - Trainings
      parameters:
        - $ref: "#/components/parameters/TrainingID"
      responses:
        "204":
          description: Training published
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"
  /v0/trainings/{trainingID}/unpublish:
    put:
      summary: Unpublish a training
      operationId: unpublishTraining
      tags:
        - Trainings
      parameters:
        - $ref: "#/components/parameters/TrainingID"
      responses:
        "204":
          description: Training unpublished
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"
  /v0/trainings/{trainingID}/retire:
    put:
      summary: Retire a training
      operationId: retireTraining
      tags:
        - Trainings
      parameters:
        - $ref: "#/components/parameters/TrainingID"
      responses:
        "204":
          description: Training retired
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"
components:
  parameters:
    TrainingID:
      name: trainingID
      in: path
      required: true
      description: ID of the training
      schema:
        $ref: "#/components/schemas/TrainingID"
    TrainingSlug:
      name: trainingSlug
      in: path
      required: true
      description: Slug of the training
      schema:
        type: string
  # Models
  schemas:
    TrainingID:
      type: integer
      minimum: 1
      x-go-type: training.ID
      x-go-type-import:
        path: gitlab.mareshq.com/hq/backoffice/backoffice-api/internal/training
    NewTraining:
      type: object
      properties:
        name:
          type: string
        slug:
          type: string
        days:
          type: integer
          format: int8
          minimum: 1
          maximum: 5
          default: 1
        pricing:
          type: array
          items:
            $ref: "#/components/schemas/TrainingPrice"
      required:
        - name
        - days
        - pricing
    Training:
      allOf:
        - $ref: "#/components/schemas/NewTraining"
        - type: object
          properties:
            id:
              $ref: "#/components/schemas/TrainingID"
            published:
              type: boolean
            retired:
              type: boolean
          required:
            - id
            - slug
            - published
            - retired
    TrainingPrice:
      allOf:
        - $ref: "#/components/schemas/Price"
        - type: object
          properties:
            type:
              type: string
              enum:
                - OPEN
                - CORPORATE
          required:
            - type
    Price:
      type: object
      properties:
        currency:
          type: string
          enum:
            - CZK
            - EUR
            - USD
          x-go-type: currency.Currency
          x-go-type-package:
            path: gitlab.mareshq.com/hq/backoffice/backoffice-api/internal/currency
        amount:
          type: string
      required:
        - currency
        - amount
    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
  # Response objects including content types
  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"
    ListTrainingsResponse:
      description: Response containing a list of trainings
      content:
        application/json:
          schema:
            type: object
            properties:
              trainings:
                type: array
                description: List of trainings
                items:
                  $ref: "#/components/schemas/Training"
    CreateTrainingResponse:
      description: Response containing a newly created training
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Training"
    GetTrainingResponse:
      description: Response containing a single training
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Training"
  # Request body objects for creating or updating resources
  requestBodies:
    CreateTrainingRequest:
      content:
        application/json:
          schema:
            type: object
            properties:
              training:
                $ref: "#/components/schemas/NewTraining"
    UpdateTrainingRequest:
      content:
        application/json:
          schema:
            type: object
            properties:
              training:
                $ref: "#/components/schemas/NewTraining"