diff --git a/api/openapi.yaml b/api/openapi.yaml new file mode 100644 index 0000000..0c5f7b4 --- /dev/null +++ b/api/openapi.yaml @@ -0,0 +1,282 @@ +openapi: "3.0.3" +info: + title: "Backoffice API" + version: "0.1.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 + parameters: + - name: limit + in: query + description: Maximum number of trainings to return + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + default: 10 + - name: offsetID + in: query + description: ID of the training to start from + required: false + schema: + type: integer + minimum: 1 + 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/by-slug/{trainingSlug}: + get: + summary: Get a training by training slug + operationId: getTrainingBySlug + tags: + - Trainings + parameters: + - $ref: "#/components/parameters/TrainingSlug" + 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: + title: + type: string + slug: + type: string + description: + type: string + days: + type: integer + minimum: 1 + maximum: 5 + default: 1 + required: + - title + - description + - days + 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 + 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" diff --git a/api/v0/openapi.yaml b/api/v0/openapi.yaml deleted file mode 100644 index e69de29..0000000