From ed5ecbd91454dddb4f96229a75cecfa734ebc424 Mon Sep 17 00:00:00 2001 From: Jan Eitzinger Date: Thu, 7 Sep 2023 15:14:09 +0200 Subject: [PATCH] fix: Restructure swagger docs --- api/swagger.json | 33 ++++++++++++++------------------- api/swagger.yaml | 28 +++++++++++++--------------- internal/api/docs.go | 33 ++++++++++++++------------------- internal/api/rest.go | 28 +++++++++++++--------------- 4 files changed, 54 insertions(+), 68 deletions(-) diff --git a/api/swagger.json b/api/swagger.json index 69d80ba..6c3bc5c 100644 --- a/api/swagger.json +++ b/api/swagger.json @@ -29,7 +29,7 @@ "application/json" ], "tags": [ - "query" + "Job query" ], "summary": "Lists all jobs", "parameters": [ @@ -127,7 +127,7 @@ "application/json" ], "tags": [ - "remove" + "Job remove" ], "summary": "Remove a job from the sql database", "parameters": [ @@ -199,7 +199,7 @@ "application/json" ], "tags": [ - "remove" + "Job remove" ], "summary": "Remove a job from the sql database", "parameters": [ @@ -269,7 +269,7 @@ "application/json" ], "tags": [ - "remove" + "Job remove" ], "summary": "Remove a job from the sql database", "parameters": [ @@ -342,7 +342,7 @@ "application/json" ], "tags": [ - "add and modify" + "Job add and modify" ], "summary": "Adds a new job as \"running\"", "parameters": [ @@ -408,7 +408,7 @@ "application/json" ], "tags": [ - "add and modify" + "Job add and modify" ], "summary": "Marks job as completed and triggers archiving", "parameters": [ @@ -483,7 +483,7 @@ "application/json" ], "tags": [ - "add and modify" + "Job add and modify" ], "summary": "Marks job as completed and triggers archiving", "parameters": [ @@ -565,7 +565,7 @@ "application/json" ], "tags": [ - "add and modify" + "Job add and modify" ], "summary": "Adds one or more tags to a job", "parameters": [ @@ -638,7 +638,7 @@ "application/json" ], "tags": [ - "query" + "Job query" ], "summary": "Get complete job meta and metric data", "parameters": [ @@ -723,7 +723,7 @@ "text/plain" ], "tags": [ - "add and modify" + "User" ], "summary": "Updates an existing user", "parameters": [ @@ -825,7 +825,7 @@ "application/json" ], "tags": [ - "query" + "User" ], "summary": "Returns a list of users", "parameters": [ @@ -887,7 +887,7 @@ "text/plain" ], "tags": [ - "add and modify" + "User" ], "summary": "Adds a new user", "parameters": [ @@ -991,7 +991,7 @@ "text/plain" ], "tags": [ - "remove" + "User" ], "summary": "Deletes a user", "parameters": [ @@ -1757,10 +1757,5 @@ "name": "X-Auth-Token", "in": "header" } - }, - "tags": [ - { - "name": "Job API" - } - ] + } } \ No newline at end of file diff --git a/api/swagger.yaml b/api/swagger.yaml index 532d5d0..cf3b3e3 100644 --- a/api/swagger.yaml +++ b/api/swagger.yaml @@ -607,7 +607,7 @@ paths: - ApiKeyAuth: [] summary: Lists all jobs tags: - - query + - Job query /jobs/{id}: post: consumes: @@ -665,7 +665,7 @@ paths: - ApiKeyAuth: [] summary: Get complete job meta and metric data tags: - - query + - Job query /jobs/delete_job/: delete: consumes: @@ -715,7 +715,7 @@ paths: - ApiKeyAuth: [] summary: Remove a job from the sql database tags: - - remove + - Job remove /jobs/delete_job/{id}: delete: description: Job to remove is specified by database ID. This will not remove @@ -762,7 +762,7 @@ paths: - ApiKeyAuth: [] summary: Remove a job from the sql database tags: - - remove + - Job remove /jobs/delete_job_before/{ts}: delete: description: Remove all jobs with start time before timestamp. The jobs will @@ -809,7 +809,7 @@ paths: - ApiKeyAuth: [] summary: Remove a job from the sql database tags: - - remove + - Job remove /jobs/start_job/: post: consumes: @@ -856,7 +856,7 @@ paths: - ApiKeyAuth: [] summary: Adds a new job as "running" tags: - - add and modify + - Job add and modify /jobs/stop_job/: post: description: |- @@ -905,7 +905,7 @@ paths: - ApiKeyAuth: [] summary: Marks job as completed and triggers archiving tags: - - add and modify + - Job add and modify /jobs/stop_job/{id}: post: consumes: @@ -961,7 +961,7 @@ paths: - ApiKeyAuth: [] summary: Marks job as completed and triggers archiving tags: - - add and modify + - Job add and modify /jobs/tag_job/{id}: post: consumes: @@ -1010,7 +1010,7 @@ paths: - ApiKeyAuth: [] summary: Adds one or more tags to a job tags: - - add and modify + - Job add and modify /user/{id}: post: consumes: @@ -1084,7 +1084,7 @@ paths: - ApiKeyAuth: [] summary: Updates an existing user tags: - - add and modify + - User /users/: delete: consumes: @@ -1127,7 +1127,7 @@ paths: - ApiKeyAuth: [] summary: Deletes a user tags: - - remove + - User get: description: |- Returns a JSON-encoded list of users. @@ -1169,7 +1169,7 @@ paths: - ApiKeyAuth: [] summary: Returns a list of users tags: - - query + - User post: consumes: - multipart/form-data @@ -1241,12 +1241,10 @@ paths: - ApiKeyAuth: [] summary: Adds a new user tags: - - add and modify + - User securityDefinitions: ApiKeyAuth: in: header name: X-Auth-Token type: apiKey swagger: "2.0" -tags: -- name: Job API diff --git a/internal/api/docs.go b/internal/api/docs.go index 009b64a..bf70cdb 100644 --- a/internal/api/docs.go +++ b/internal/api/docs.go @@ -36,7 +36,7 @@ const docTemplate = `{ "application/json" ], "tags": [ - "query" + "Job query" ], "summary": "Lists all jobs", "parameters": [ @@ -134,7 +134,7 @@ const docTemplate = `{ "application/json" ], "tags": [ - "remove" + "Job remove" ], "summary": "Remove a job from the sql database", "parameters": [ @@ -206,7 +206,7 @@ const docTemplate = `{ "application/json" ], "tags": [ - "remove" + "Job remove" ], "summary": "Remove a job from the sql database", "parameters": [ @@ -276,7 +276,7 @@ const docTemplate = `{ "application/json" ], "tags": [ - "remove" + "Job remove" ], "summary": "Remove a job from the sql database", "parameters": [ @@ -349,7 +349,7 @@ const docTemplate = `{ "application/json" ], "tags": [ - "add and modify" + "Job add and modify" ], "summary": "Adds a new job as \"running\"", "parameters": [ @@ -415,7 +415,7 @@ const docTemplate = `{ "application/json" ], "tags": [ - "add and modify" + "Job add and modify" ], "summary": "Marks job as completed and triggers archiving", "parameters": [ @@ -490,7 +490,7 @@ const docTemplate = `{ "application/json" ], "tags": [ - "add and modify" + "Job add and modify" ], "summary": "Marks job as completed and triggers archiving", "parameters": [ @@ -572,7 +572,7 @@ const docTemplate = `{ "application/json" ], "tags": [ - "add and modify" + "Job add and modify" ], "summary": "Adds one or more tags to a job", "parameters": [ @@ -645,7 +645,7 @@ const docTemplate = `{ "application/json" ], "tags": [ - "query" + "Job query" ], "summary": "Get complete job meta and metric data", "parameters": [ @@ -730,7 +730,7 @@ const docTemplate = `{ "text/plain" ], "tags": [ - "add and modify" + "User" ], "summary": "Updates an existing user", "parameters": [ @@ -832,7 +832,7 @@ const docTemplate = `{ "application/json" ], "tags": [ - "query" + "User" ], "summary": "Returns a list of users", "parameters": [ @@ -894,7 +894,7 @@ const docTemplate = `{ "text/plain" ], "tags": [ - "add and modify" + "User" ], "summary": "Adds a new user", "parameters": [ @@ -998,7 +998,7 @@ const docTemplate = `{ "text/plain" ], "tags": [ - "remove" + "User" ], "summary": "Deletes a user", "parameters": [ @@ -1764,12 +1764,7 @@ const docTemplate = `{ "name": "X-Auth-Token", "in": "header" } - }, - "tags": [ - { - "name": "Job API" - } - ] + } }` // SwaggerInfo holds exported Swagger Info so clients can modify it diff --git a/internal/api/rest.go b/internal/api/rest.go index a6e33fc..1cb2cac 100644 --- a/internal/api/rest.go +++ b/internal/api/rest.go @@ -37,8 +37,6 @@ import ( // @version 1.0.0 // @description API for batch job control. -// @tag.name Job API - // @contact.name ClusterCockpit Project // @contact.url https://github.com/ClusterCockpit // @contact.email support@clustercockpit.org @@ -223,7 +221,7 @@ func securedCheck(r *http.Request) error { // getJobs godoc // @summary Lists all jobs -// @tags query +// @tags Job query // @description Get a list of all jobs. Filters can be applied using query parameters. // @description Number of results can be limited by page. Results are sorted by descending startTime. // @produce json @@ -369,7 +367,7 @@ func (api *RestApi) getJobs(rw http.ResponseWriter, r *http.Request) { // getJobById godoc // @summary Get complete job meta and metric data -// @tags query +// @tags Job query // @description Job to get is specified by database ID // @description Returns full job resource information according to 'JobMeta' scheme and all metrics according to 'JobData'. // @accept json @@ -464,7 +462,7 @@ func (api *RestApi) getJobById(rw http.ResponseWriter, r *http.Request) { // tagJob godoc // @summary Adds one or more tags to a job -// @tags add and modify +// @tags Job add and modify // @description Adds tag(s) to a job specified by DB ID. Name and Type of Tag(s) can be chosen freely. // @description If tagged job is already finished: Tag will be written directly to respective archive files. // @accept json @@ -531,7 +529,7 @@ func (api *RestApi) tagJob(rw http.ResponseWriter, r *http.Request) { // startJob godoc // @summary Adds a new job as "running" -// @tags add and modify +// @tags Job add and modify // @description Job specified in request body will be saved to database as "running" with new DB ID. // @description Job specifications follow the 'JobMeta' scheme, API will fail to execute if requirements are not met. // @accept json @@ -612,7 +610,7 @@ func (api *RestApi) startJob(rw http.ResponseWriter, r *http.Request) { // stopJobById godoc // @summary Marks job as completed and triggers archiving -// @tags add and modify +// @tags Job add and modify // @description Job to stop is specified by database ID. Only stopTime and final state are required in request body. // @description Returns full job resource information according to 'JobMeta' scheme. // @accept json @@ -669,7 +667,7 @@ func (api *RestApi) stopJobById(rw http.ResponseWriter, r *http.Request) { // stopJobByRequest godoc // @summary Marks job as completed and triggers archiving -// @tags add and modify +// @tags Job add and modify // @description Job to stop is specified by request body. All fields are required in this case. // @description Returns full job resource information according to 'JobMeta' scheme. // @produce json @@ -718,7 +716,7 @@ func (api *RestApi) stopJobByRequest(rw http.ResponseWriter, r *http.Request) { // deleteJobById godoc // @summary Remove a job from the sql database -// @tags remove +// @tags Job remove // @description Job to remove is specified by database ID. This will not remove the job from the job archive. // @produce json // @param id path int true "Database ID of Job" @@ -765,7 +763,7 @@ func (api *RestApi) deleteJobById(rw http.ResponseWriter, r *http.Request) { // deleteJobByRequest godoc // @summary Remove a job from the sql database -// @tags remove +// @tags Job remove // @description Job to delete is specified by request body. All fields are required in this case. // @accept json // @produce json @@ -823,7 +821,7 @@ func (api *RestApi) deleteJobByRequest(rw http.ResponseWriter, r *http.Request) // deleteJobBefore godoc // @summary Remove a job from the sql database -// @tags remove +// @tags Job remove // @description Remove all jobs with start time before timestamp. The jobs will not be removed from the job archive. // @produce json // @param ts path int true "Unix epoch timestamp" @@ -955,7 +953,7 @@ func (api *RestApi) getJobMetrics(rw http.ResponseWriter, r *http.Request) { // createUser godoc // @summary Adds a new user -// @tags add and modify +// @tags User // @description User specified in form data will be saved to database. // @description Only accessible from IPs registered with apiAllowedIPs configuration option. // @accept mpfd @@ -1023,7 +1021,7 @@ func (api *RestApi) createUser(rw http.ResponseWriter, r *http.Request) { // deleteUser godoc // @summary Deletes a user -// @tags remove +// @tags User // @description User defined by username in form data will be deleted from database. // @description Only accessible from IPs registered with apiAllowedIPs configuration option. // @accept mpfd @@ -1060,7 +1058,7 @@ func (api *RestApi) deleteUser(rw http.ResponseWriter, r *http.Request) { // getUsers godoc // @summary Returns a list of users -// @tags query +// @tags User // @description Returns a JSON-encoded list of users. // @description Required query-parameter defines if all users or only users with additional special roles are returned. // @description Only accessible from IPs registered with apiAllowedIPs configuration option. @@ -1096,7 +1094,7 @@ func (api *RestApi) getUsers(rw http.ResponseWriter, r *http.Request) { // updateUser godoc // @summary Updates an existing user -// @tags add and modify +// @tags User // @description Modifies user defined by username (id) in one of four possible ways. // @description If more than one formValue is set then only the highest priority field is used. // @description Only accessible from IPs registered with apiAllowedIPs configuration option.