From 872bc77708f86e89b7a2cd1f1ab5dd3cb6ffa61e Mon Sep 17 00:00:00 2001 From: Christoph Kluge Date: Wed, 21 Sep 2022 17:03:01 +0200 Subject: [PATCH] Add missing error codes to documentation, fix wrong success type --- api/swagger.json | 66 ++++++++++++++++++++++++++++++++++++++++-- api/swagger.yaml | 50 +++++++++++++++++++++++++++++--- internal/api/docs.go | 68 +++++++++++++++++++++++++++++++++++++++++--- internal/api/rest.go | 16 +++++++++-- 4 files changed, 186 insertions(+), 14 deletions(-) diff --git a/api/swagger.json b/api/swagger.json index a221ea4..2aaad29 100644 --- a/api/swagger.json +++ b/api/swagger.json @@ -94,6 +94,12 @@ "schema": { "$ref": "#/definitions/api.ErrorResponse" } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/api.ErrorResponse" + } } } } @@ -137,8 +143,20 @@ "$ref": "#/definitions/api.ErrorResponse" } }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/api.ErrorResponse" + } + }, "422": { - "description": "The combination of jobId, clusterId and startTime does already exist", + "description": "Unprocessable Entity: The combination of jobId, clusterId and startTime does already exist", + "schema": { + "$ref": "#/definitions/api.ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", "schema": { "$ref": "#/definitions/api.ErrorResponse" } @@ -170,7 +188,7 @@ } ], "responses": { - "201": { + "200": { "description": "Job resource", "schema": { "$ref": "#/definitions/schema.JobMeta" @@ -182,11 +200,29 @@ "$ref": "#/definitions/api.ErrorResponse" } }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/api.ErrorResponse" + } + }, "404": { "description": "Resource not found", "schema": { "$ref": "#/definitions/api.ErrorResponse" } + }, + "422": { + "description": "Unprocessable Entity: finding job failed: sql: no rows in result set", + "schema": { + "$ref": "#/definitions/api.ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/api.ErrorResponse" + } } } } @@ -225,7 +261,7 @@ } ], "responses": { - "201": { + "200": { "description": "Job resource", "schema": { "$ref": "#/definitions/schema.JobMeta" @@ -237,11 +273,29 @@ "$ref": "#/definitions/api.ErrorResponse" } }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/api.ErrorResponse" + } + }, "404": { "description": "Resource not found", "schema": { "$ref": "#/definitions/api.ErrorResponse" } + }, + "422": { + "description": "Unprocessable Entity: finding job failed: sql: no rows in result set", + "schema": { + "$ref": "#/definitions/api.ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/api.ErrorResponse" + } } } } @@ -300,6 +354,12 @@ "schema": { "$ref": "#/definitions/api.ErrorResponse" } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/api.ErrorResponse" + } } } } diff --git a/api/swagger.yaml b/api/swagger.yaml index 4e47530..1e46b28 100644 --- a/api/swagger.yaml +++ b/api/swagger.yaml @@ -408,6 +408,10 @@ paths: description: Bad Request schema: $ref: '#/definitions/api.ErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/api.ErrorResponse' security: - ApiKeyAuth: [] summary: Lists all jobs @@ -436,9 +440,17 @@ paths: description: Bad Request schema: $ref: '#/definitions/api.ErrorResponse' + "403": + description: Forbidden + schema: + $ref: '#/definitions/api.ErrorResponse' "422": - description: The combination of jobId, clusterId and startTime does already - exist + description: 'Unprocessable Entity: The combination of jobId, clusterId + and startTime does already exist' + schema: + $ref: '#/definitions/api.ErrorResponse' + "500": + description: Internal Server Error schema: $ref: '#/definitions/api.ErrorResponse' security: @@ -459,7 +471,7 @@ paths: produces: - application/json responses: - "201": + "200": description: Job resource schema: $ref: '#/definitions/schema.JobMeta' @@ -467,10 +479,23 @@ paths: description: Bad Request schema: $ref: '#/definitions/api.ErrorResponse' + "403": + description: Forbidden + schema: + $ref: '#/definitions/api.ErrorResponse' "404": description: Resource not found schema: $ref: '#/definitions/api.ErrorResponse' + "422": + description: 'Unprocessable Entity: finding job failed: sql: no rows in + result set' + schema: + $ref: '#/definitions/api.ErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/api.ErrorResponse' security: - ApiKeyAuth: [] summary: Marks job as completed and triggers archiving @@ -496,7 +521,7 @@ paths: produces: - application/json responses: - "201": + "200": description: Job resource schema: $ref: '#/definitions/schema.JobMeta' @@ -504,10 +529,23 @@ paths: description: Bad Request schema: $ref: '#/definitions/api.ErrorResponse' + "403": + description: Forbidden + schema: + $ref: '#/definitions/api.ErrorResponse' "404": description: Resource not found schema: $ref: '#/definitions/api.ErrorResponse' + "422": + description: 'Unprocessable Entity: finding job failed: sql: no rows in + result set' + schema: + $ref: '#/definitions/api.ErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/api.ErrorResponse' security: - ApiKeyAuth: [] summary: Marks job as completed and triggers archiving @@ -547,6 +585,10 @@ paths: description: Job or tag does not exist schema: $ref: '#/definitions/api.ErrorResponse' + "500": + description: Internal Server Error + schema: + $ref: '#/definitions/api.ErrorResponse' security: - ApiKeyAuth: [] summary: Adds one or more tags to a job diff --git a/internal/api/docs.go b/internal/api/docs.go index 0007060..eb4db11 100644 --- a/internal/api/docs.go +++ b/internal/api/docs.go @@ -1,6 +1,6 @@ // Package api GENERATED BY SWAG; DO NOT EDIT // This file was generated by swaggo/swag at -// 2022-09-21 14:20:28.235814518 +0200 CEST m=+0.133704544 +// 2022-09-21 16:59:20.417950914 +0200 CEST m=+0.112710428 package api import "github.com/swaggo/swag" @@ -102,6 +102,12 @@ const docTemplate = `{ "schema": { "$ref": "#/definitions/api.ErrorResponse" } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/api.ErrorResponse" + } } } } @@ -145,8 +151,20 @@ const docTemplate = `{ "$ref": "#/definitions/api.ErrorResponse" } }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/api.ErrorResponse" + } + }, "422": { - "description": "The combination of jobId, clusterId and startTime does already exist", + "description": "Unprocessable Entity: The combination of jobId, clusterId and startTime does already exist", + "schema": { + "$ref": "#/definitions/api.ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", "schema": { "$ref": "#/definitions/api.ErrorResponse" } @@ -178,7 +196,7 @@ const docTemplate = `{ } ], "responses": { - "201": { + "200": { "description": "Job resource", "schema": { "$ref": "#/definitions/schema.JobMeta" @@ -190,11 +208,29 @@ const docTemplate = `{ "$ref": "#/definitions/api.ErrorResponse" } }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/api.ErrorResponse" + } + }, "404": { "description": "Resource not found", "schema": { "$ref": "#/definitions/api.ErrorResponse" } + }, + "422": { + "description": "Unprocessable Entity: finding job failed: sql: no rows in result set", + "schema": { + "$ref": "#/definitions/api.ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/api.ErrorResponse" + } } } } @@ -233,7 +269,7 @@ const docTemplate = `{ } ], "responses": { - "201": { + "200": { "description": "Job resource", "schema": { "$ref": "#/definitions/schema.JobMeta" @@ -245,11 +281,29 @@ const docTemplate = `{ "$ref": "#/definitions/api.ErrorResponse" } }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/api.ErrorResponse" + } + }, "404": { "description": "Resource not found", "schema": { "$ref": "#/definitions/api.ErrorResponse" } + }, + "422": { + "description": "Unprocessable Entity: finding job failed: sql: no rows in result set", + "schema": { + "$ref": "#/definitions/api.ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/api.ErrorResponse" + } } } } @@ -308,6 +362,12 @@ const docTemplate = `{ "schema": { "$ref": "#/definitions/api.ErrorResponse" } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/api.ErrorResponse" + } } } } diff --git a/internal/api/rest.go b/internal/api/rest.go index 1ca7d20..95fca07 100644 --- a/internal/api/rest.go +++ b/internal/api/rest.go @@ -154,6 +154,7 @@ func decode(r io.Reader, val interface{}) error { // @Param with-metadata query bool false "Include metadata in response" // @Success 200 {array} schema.Job "Array of jobs" // @Failure 400 {object} api.ErrorResponse "Bad Request" +// @Failure 500 {object} api.ErrorResponse "Internal Server Error" // @Security ApiKeyAuth // @Router /jobs/ [get] func (api *RestApi) getJobs(rw http.ResponseWriter, r *http.Request) { @@ -276,6 +277,7 @@ func (api *RestApi) getJobs(rw http.ResponseWriter, r *http.Request) { // @Success 200 {object} schema.Job "Job resource" // @Failure 400 {object} api.ErrorResponse "Bad Request" // @Failure 404 {object} api.ErrorResponse "Job or tag does not exist" +// @Failure 500 {object} api.ErrorResponse "Internal Server Error" // @Security ApiKeyAuth // @Router /jobs/tag_job/{id} [post] func (api *RestApi) tagJob(rw http.ResponseWriter, r *http.Request) { @@ -331,7 +333,9 @@ func (api *RestApi) tagJob(rw http.ResponseWriter, r *http.Request) { // @Param request body schema.JobMeta true "Job to add" // @Success 201 {object} api.StartJobApiResponse "Job added successfully" // @Failure 400 {object} api.ErrorResponse "Bad Request" -// @Failure 422 {object} api.ErrorResponse "The combination of jobId, clusterId and startTime does already exist" +// @Failure 403 {object} api.ErrorResponse "Forbidden" +// @Failure 422 {object} api.ErrorResponse "Unprocessable Entity: The combination of jobId, clusterId and startTime does already exist" +// @Failure 500 {object} api.ErrorResponse "Internal Server Error" // @Security ApiKeyAuth // @Router /jobs/start_job/ [post] func (api *RestApi) startJob(rw http.ResponseWriter, r *http.Request) { @@ -396,9 +400,12 @@ func (api *RestApi) startJob(rw http.ResponseWriter, r *http.Request) { // @Produce json // @Param id path int true "Database ID of Job" // @Param request body api.StopJobApiRequest true "stopTime and final state in request body" -// @Success 201 {object} schema.JobMeta "Job resource" +// @Success 200 {object} schema.JobMeta "Job resource" // @Failure 400 {object} api.ErrorResponse "Bad Request" +// @Failure 403 {object} api.ErrorResponse "Forbidden" // @Failure 404 {object} api.ErrorResponse "Resource not found" +// @Failure 422 {object} api.ErrorResponse "Unprocessable Entity: finding job failed: sql: no rows in result set" +// @Failure 500 {object} api.ErrorResponse "Internal Server Error" // @Security ApiKeyAuth // @Router /jobs/stop_job/{id} [post] func (api *RestApi) stopJobById(rw http.ResponseWriter, r *http.Request) { @@ -505,9 +512,12 @@ func (api *RestApi) stopJobById(rw http.ResponseWriter, r *http.Request) { // @Description Returns full job resource information according to 'JobMeta' scheme. // @Produce json // @Param request body api.StopJobApiRequest true "All fields required" -// @Success 201 {object} schema.JobMeta "Job resource" +// @Success 200 {object} schema.JobMeta "Job resource" // @Failure 400 {object} api.ErrorResponse "Bad Request" +// @Failure 403 {object} api.ErrorResponse "Forbidden" // @Failure 404 {object} api.ErrorResponse "Resource not found" +// @Failure 422 {object} api.ErrorResponse "Unprocessable Entity: finding job failed: sql: no rows in result set" +// @Failure 500 {object} api.ErrorResponse "Internal Server Error" // @Security ApiKeyAuth // @Router /jobs/stop_job/ [post] func (api *RestApi) stopJobByRequest(rw http.ResponseWriter, r *http.Request) {