ClusterCockpit/cc-backend
1
0
Fork 0
mirror of https://github.com/ClusterCockpit/cc-backend synced 2024-12-26 13:29:05 +01:00
Code Issues Packages Releases Activity

fix: Restructure swagger docs

Browse Source
This commit is contained in:
Jan Eitzinger 2023-09-07 15:14:09 +02:00
parent 2d4759114e
commit ed5ecbd914
4 changed files with 54 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
api/swagger.json
View File

@ -29,7 +29,7 @@
"application/json" "application/json"
], ],
"tags": [ "tags": [
"query" "Job query"
], ],
"summary": "Lists all jobs", "summary": "Lists all jobs",
"parameters": [ "parameters": [
@ -127,7 +127,7 @@
"application/json" "application/json"
], ],
"tags": [ "tags": [
"remove" "Job remove"
], ],
"summary": "Remove a job from the sql database", "summary": "Remove a job from the sql database",
"parameters": [ "parameters": [
@ -199,7 +199,7 @@
"application/json" "application/json"
], ],
"tags": [ "tags": [
"remove" "Job remove"
], ],
"summary": "Remove a job from the sql database", "summary": "Remove a job from the sql database",
"parameters": [ "parameters": [
@ -269,7 +269,7 @@
"application/json" "application/json"
], ],
"tags": [ "tags": [
"remove" "Job remove"
], ],
"summary": "Remove a job from the sql database", "summary": "Remove a job from the sql database",
"parameters": [ "parameters": [
@ -342,7 +342,7 @@
"application/json" "application/json"
], ],
"tags": [ "tags": [
"add and modify" "Job add and modify"
], ],
"summary": "Adds a new job as \"running\"", "summary": "Adds a new job as \"running\"",
"parameters": [ "parameters": [
@ -408,7 +408,7 @@
"application/json" "application/json"
], ],
"tags": [ "tags": [
"add and modify" "Job add and modify"
], ],
"summary": "Marks job as completed and triggers archiving", "summary": "Marks job as completed and triggers archiving",
"parameters": [ "parameters": [
@ -483,7 +483,7 @@
"application/json" "application/json"
], ],
"tags": [ "tags": [
"add and modify" "Job add and modify"
], ],
"summary": "Marks job as completed and triggers archiving", "summary": "Marks job as completed and triggers archiving",
"parameters": [ "parameters": [
@ -565,7 +565,7 @@
"application/json" "application/json"
], ],
"tags": [ "tags": [
"add and modify" "Job add and modify"
], ],
"summary": "Adds one or more tags to a job", "summary": "Adds one or more tags to a job",
"parameters": [ "parameters": [
@ -638,7 +638,7 @@
"application/json" "application/json"
], ],
"tags": [ "tags": [
"query" "Job query"
], ],
"summary": "Get complete job meta and metric data", "summary": "Get complete job meta and metric data",
"parameters": [ "parameters": [
@ -723,7 +723,7 @@
"text/plain" "text/plain"
], ],
"tags": [ "tags": [
"add and modify" "User"
], ],
"summary": "Updates an existing user", "summary": "Updates an existing user",
"parameters": [ "parameters": [
@ -825,7 +825,7 @@
"application/json" "application/json"
], ],
"tags": [ "tags": [
"query" "User"
], ],
"summary": "Returns a list of users", "summary": "Returns a list of users",
"parameters": [ "parameters": [
@ -887,7 +887,7 @@
"text/plain" "text/plain"
], ],
"tags": [ "tags": [
"add and modify" "User"
], ],
"summary": "Adds a new user", "summary": "Adds a new user",
"parameters": [ "parameters": [
@ -991,7 +991,7 @@
"text/plain" "text/plain"
], ],
"tags": [ "tags": [
"remove" "User"
], ],
"summary": "Deletes a user", "summary": "Deletes a user",
"parameters": [ "parameters": [
@ -1757,10 +1757,5 @@
"name": "X-Auth-Token", "name": "X-Auth-Token",
"in": "header" "in": "header"
} }
},
"tags": [
{
"name": "Job API"
} }
]
} }

28
api/swagger.yaml
View File

@ -607,7 +607,7 @@ paths:
- ApiKeyAuth: [] - ApiKeyAuth: []
summary: Lists all jobs summary: Lists all jobs
tags: tags:
- query - Job query
/jobs/{id}: /jobs/{id}:
post: post:
consumes: consumes:
@ -665,7 +665,7 @@ paths:
- ApiKeyAuth: [] - ApiKeyAuth: []
summary: Get complete job meta and metric data summary: Get complete job meta and metric data
tags: tags:
- query - Job query
/jobs/delete_job/: /jobs/delete_job/:
delete: delete:
consumes: consumes:
@ -715,7 +715,7 @@ paths:
- ApiKeyAuth: [] - ApiKeyAuth: []
summary: Remove a job from the sql database summary: Remove a job from the sql database
tags: tags:
- remove - Job remove
/jobs/delete_job/{id}: /jobs/delete_job/{id}:
delete: delete:
description: Job to remove is specified by database ID. This will not remove description: Job to remove is specified by database ID. This will not remove
@ -762,7 +762,7 @@ paths:
- ApiKeyAuth: [] - ApiKeyAuth: []
summary: Remove a job from the sql database summary: Remove a job from the sql database
tags: tags:
- remove - Job remove
/jobs/delete_job_before/{ts}: /jobs/delete_job_before/{ts}:
delete: delete:
description: Remove all jobs with start time before timestamp. The jobs will description: Remove all jobs with start time before timestamp. The jobs will
@ -809,7 +809,7 @@ paths:
- ApiKeyAuth: [] - ApiKeyAuth: []
summary: Remove a job from the sql database summary: Remove a job from the sql database
tags: tags:
- remove - Job remove
/jobs/start_job/: /jobs/start_job/:
post: post:
consumes: consumes:
@ -856,7 +856,7 @@ paths:
- ApiKeyAuth: [] - ApiKeyAuth: []
summary: Adds a new job as "running" summary: Adds a new job as "running"
tags: tags:
- add and modify - Job add and modify
/jobs/stop_job/: /jobs/stop_job/:
post: post:
description: |- description: |-
@ -905,7 +905,7 @@ paths:
- ApiKeyAuth: [] - ApiKeyAuth: []
summary: Marks job as completed and triggers archiving summary: Marks job as completed and triggers archiving
tags: tags:
- add and modify - Job add and modify
/jobs/stop_job/{id}: /jobs/stop_job/{id}:
post: post:
consumes: consumes:
@ -961,7 +961,7 @@ paths:
- ApiKeyAuth: [] - ApiKeyAuth: []
summary: Marks job as completed and triggers archiving summary: Marks job as completed and triggers archiving
tags: tags:
- add and modify - Job add and modify
/jobs/tag_job/{id}: /jobs/tag_job/{id}:
post: post:
consumes: consumes:
@ -1010,7 +1010,7 @@ paths:
- ApiKeyAuth: [] - ApiKeyAuth: []
summary: Adds one or more tags to a job summary: Adds one or more tags to a job
tags: tags:
- add and modify - Job add and modify
/user/{id}: /user/{id}:
post: post:
consumes: consumes:
@ -1084,7 +1084,7 @@ paths:
- ApiKeyAuth: [] - ApiKeyAuth: []
summary: Updates an existing user summary: Updates an existing user
tags: tags:
- add and modify - User
/users/: /users/:
delete: delete:
consumes: consumes:
@ -1127,7 +1127,7 @@ paths:
- ApiKeyAuth: [] - ApiKeyAuth: []
summary: Deletes a user summary: Deletes a user
tags: tags:
- remove - User
get: get:
description: |- description: |-
Returns a JSON-encoded list of users. Returns a JSON-encoded list of users.
@ -1169,7 +1169,7 @@ paths:
- ApiKeyAuth: [] - ApiKeyAuth: []
summary: Returns a list of users summary: Returns a list of users
tags: tags:
- query - User
post: post:
consumes: consumes:
- multipart/form-data - multipart/form-data
@ -1241,12 +1241,10 @@ paths:
- ApiKeyAuth: [] - ApiKeyAuth: []
summary: Adds a new user summary: Adds a new user
tags: tags:
- add and modify - User
securityDefinitions: securityDefinitions:
ApiKeyAuth: ApiKeyAuth:
in: header in: header
name: X-Auth-Token name: X-Auth-Token
type: apiKey type: apiKey
swagger: "2.0" swagger: "2.0"
tags:
- name: Job API

31
internal/api/docs.go
View File

@ -36,7 +36,7 @@ const docTemplate = `{
"application/json" "application/json"
], ],
"tags": [ "tags": [
"query" "Job query"
], ],
"summary": "Lists all jobs", "summary": "Lists all jobs",
"parameters": [ "parameters": [
@ -134,7 +134,7 @@ const docTemplate = `{
"application/json" "application/json"
], ],
"tags": [ "tags": [
"remove" "Job remove"
], ],
"summary": "Remove a job from the sql database", "summary": "Remove a job from the sql database",
"parameters": [ "parameters": [
@ -206,7 +206,7 @@ const docTemplate = `{
"application/json" "application/json"
], ],
"tags": [ "tags": [
"remove" "Job remove"
], ],
"summary": "Remove a job from the sql database", "summary": "Remove a job from the sql database",
"parameters": [ "parameters": [
@ -276,7 +276,7 @@ const docTemplate = `{
"application/json" "application/json"
], ],
"tags": [ "tags": [
"remove" "Job remove"
], ],
"summary": "Remove a job from the sql database", "summary": "Remove a job from the sql database",
"parameters": [ "parameters": [
@ -349,7 +349,7 @@ const docTemplate = `{
"application/json" "application/json"
], ],
"tags": [ "tags": [
"add and modify" "Job add and modify"
], ],
"summary": "Adds a new job as \"running\"", "summary": "Adds a new job as \"running\"",
"parameters": [ "parameters": [
@ -415,7 +415,7 @@ const docTemplate = `{
"application/json" "application/json"
], ],
"tags": [ "tags": [
"add and modify" "Job add and modify"
], ],
"summary": "Marks job as completed and triggers archiving", "summary": "Marks job as completed and triggers archiving",
"parameters": [ "parameters": [
@ -490,7 +490,7 @@ const docTemplate = `{
"application/json" "application/json"
], ],
"tags": [ "tags": [
"add and modify" "Job add and modify"
], ],
"summary": "Marks job as completed and triggers archiving", "summary": "Marks job as completed and triggers archiving",
"parameters": [ "parameters": [
@ -572,7 +572,7 @@ const docTemplate = `{
"application/json" "application/json"
], ],
"tags": [ "tags": [
"add and modify" "Job add and modify"
], ],
"summary": "Adds one or more tags to a job", "summary": "Adds one or more tags to a job",
"parameters": [ "parameters": [
@ -645,7 +645,7 @@ const docTemplate = `{
"application/json" "application/json"
], ],
"tags": [ "tags": [
"query" "Job query"
], ],
"summary": "Get complete job meta and metric data", "summary": "Get complete job meta and metric data",
"parameters": [ "parameters": [
@ -730,7 +730,7 @@ const docTemplate = `{
"text/plain" "text/plain"
], ],
"tags": [ "tags": [
"add and modify" "User"
], ],
"summary": "Updates an existing user", "summary": "Updates an existing user",
"parameters": [ "parameters": [
@ -832,7 +832,7 @@ const docTemplate = `{
"application/json" "application/json"
], ],
"tags": [ "tags": [
"query" "User"
], ],
"summary": "Returns a list of users", "summary": "Returns a list of users",
"parameters": [ "parameters": [
@ -894,7 +894,7 @@ const docTemplate = `{
"text/plain" "text/plain"
], ],
"tags": [ "tags": [
"add and modify" "User"
], ],
"summary": "Adds a new user", "summary": "Adds a new user",
"parameters": [ "parameters": [
@ -998,7 +998,7 @@ const docTemplate = `{
"text/plain" "text/plain"
], ],
"tags": [ "tags": [
"remove" "User"
], ],
"summary": "Deletes a user", "summary": "Deletes a user",
"parameters": [ "parameters": [
@ -1764,12 +1764,7 @@ const docTemplate = `{
"name": "X-Auth-Token", "name": "X-Auth-Token",
"in": "header" "in": "header"
} }
},
"tags": [
{
"name": "Job API"
} }
]
}` }`
// SwaggerInfo holds exported Swagger Info so clients can modify it // SwaggerInfo holds exported Swagger Info so clients can modify it

28
internal/api/rest.go
View File

@ -37,8 +37,6 @@ import (
// @version 1.0.0 // @version 1.0.0
// @description API for batch job control. // @description API for batch job control.
// @tag.name Job API
// @contact.name ClusterCockpit Project // @contact.name ClusterCockpit Project
// @contact.url https://github.com/ClusterCockpit // @contact.url https://github.com/ClusterCockpit
// @contact.email support@clustercockpit.org // @contact.email support@clustercockpit.org
@ -223,7 +221,7 @@ func securedCheck(r *http.Request) error {
// getJobs godoc // getJobs godoc
// @summary Lists all jobs // @summary Lists all jobs
// @tags query // @tags Job query
// @description Get a list of all jobs. Filters can be applied using query parameters. // @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. // @description Number of results can be limited by page. Results are sorted by descending startTime.
// @produce json // @produce json
@ -369,7 +367,7 @@ func (api *RestApi) getJobs(rw http.ResponseWriter, r *http.Request) {
// getJobById godoc // getJobById godoc
// @summary Get complete job meta and metric data // @summary Get complete job meta and metric data
// @tags query // @tags Job query
// @description Job to get is specified by database ID // @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'. // @description Returns full job resource information according to 'JobMeta' scheme and all metrics according to 'JobData'.
// @accept json // @accept json
@ -464,7 +462,7 @@ func (api *RestApi) getJobById(rw http.ResponseWriter, r *http.Request) {
// tagJob godoc // tagJob godoc
// @summary Adds one or more tags to a job // @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 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. // @description If tagged job is already finished: Tag will be written directly to respective archive files.
// @accept json // @accept json
@ -531,7 +529,7 @@ func (api *RestApi) tagJob(rw http.ResponseWriter, r *http.Request) {
// startJob godoc // startJob godoc
// @summary Adds a new job as "running" // @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 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. // @description Job specifications follow the 'JobMeta' scheme, API will fail to execute if requirements are not met.
// @accept json // @accept json
@ -612,7 +610,7 @@ func (api *RestApi) startJob(rw http.ResponseWriter, r *http.Request) {
// stopJobById godoc // stopJobById godoc
// @summary Marks job as completed and triggers archiving // @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 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. // @description Returns full job resource information according to 'JobMeta' scheme.
// @accept json // @accept json
@ -669,7 +667,7 @@ func (api *RestApi) stopJobById(rw http.ResponseWriter, r *http.Request) {
// stopJobByRequest godoc // stopJobByRequest godoc
// @summary Marks job as completed and triggers archiving // @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 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. // @description Returns full job resource information according to 'JobMeta' scheme.
// @produce json // @produce json
@ -718,7 +716,7 @@ func (api *RestApi) stopJobByRequest(rw http.ResponseWriter, r *http.Request) {
// deleteJobById godoc // deleteJobById godoc
// @summary Remove a job from the sql database // @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. // @description Job to remove is specified by database ID. This will not remove the job from the job archive.
// @produce json // @produce json
// @param id path int true "Database ID of Job" // @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 // deleteJobByRequest godoc
// @summary Remove a job from the sql database // @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. // @description Job to delete is specified by request body. All fields are required in this case.
// @accept json // @accept json
// @produce json // @produce json
@ -823,7 +821,7 @@ func (api *RestApi) deleteJobByRequest(rw http.ResponseWriter, r *http.Request)
// deleteJobBefore godoc // deleteJobBefore godoc
// @summary Remove a job from the sql database // @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. // @description Remove all jobs with start time before timestamp. The jobs will not be removed from the job archive.
// @produce json // @produce json
// @param ts path int true "Unix epoch timestamp" // @param ts path int true "Unix epoch timestamp"
@ -955,7 +953,7 @@ func (api *RestApi) getJobMetrics(rw http.ResponseWriter, r *http.Request) {
// createUser godoc // createUser godoc
// @summary Adds a new user // @summary Adds a new user
// @tags add and modify // @tags User
// @description User specified in form data will be saved to database. // @description User specified in form data will be saved to database.
// @description Only accessible from IPs registered with apiAllowedIPs configuration option. // @description Only accessible from IPs registered with apiAllowedIPs configuration option.
// @accept mpfd // @accept mpfd
@ -1023,7 +1021,7 @@ func (api *RestApi) createUser(rw http.ResponseWriter, r *http.Request) {
// deleteUser godoc // deleteUser godoc
// @summary Deletes a user // @summary Deletes a user
// @tags remove // @tags User
// @description User defined by username in form data will be deleted from database. // @description User defined by username in form data will be deleted from database.
// @description Only accessible from IPs registered with apiAllowedIPs configuration option. // @description Only accessible from IPs registered with apiAllowedIPs configuration option.
// @accept mpfd // @accept mpfd
@ -1060,7 +1058,7 @@ func (api *RestApi) deleteUser(rw http.ResponseWriter, r *http.Request) {
// getUsers godoc // getUsers godoc
// @summary Returns a list of users // @summary Returns a list of users
// @tags query // @tags User
// @description Returns a JSON-encoded list of users. // @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 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. // @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 // updateUser godoc
// @summary Updates an existing user // @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 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 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. // @description Only accessible from IPs registered with apiAllowedIPs configuration option.