ClusterCockpit/cc-backend
1
0
Fork 0
mirror of https://github.com/ClusterCockpit/cc-backend synced 2024-09-20 03:17:26 +02: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"
],
"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"
}
]
}

28
api/swagger.yaml
View File

@ -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

31
internal/api/docs.go
View File

@ -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

28
internal/api/rest.go
View File

@ -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.