From f36f62fb4776fc7a530fbb31bc0883964cb07530 Mon Sep 17 00:00:00 2001 From: Christoph Kluge Date: Mon, 21 Aug 2023 12:12:28 +0200 Subject: [PATCH] Improve user endpoint swagger docs --- api/swagger.json | 108 +++++++++++++++++++++++++++++++------------ api/swagger.yaml | 95 +++++++++++++++++++++++++------------ internal/api/docs.go | 108 +++++++++++++++++++++++++++++++------------ internal/api/rest.go | 68 +++++++++++++++------------ 4 files changed, 261 insertions(+), 118 deletions(-) diff --git a/api/swagger.json b/api/swagger.json index 2a4c43a..dfc2f75 100644 --- a/api/swagger.json +++ b/api/swagger.json @@ -735,14 +735,28 @@ "required": true }, { + "enum": [ + "admin", + "support", + "manager", + "user", + "api" + ], "type": "string", - "description": "Priority 1: Role to add, one of: [admin, support, manager, user, api]", + "description": "Priority 1: Role to add", "name": "add-role", "in": "formData" }, { + "enum": [ + "admin", + "support", + "manager", + "user", + "api" + ], "type": "string", - "description": "Priority 2: Role to remove, one of: [admin, support, manager, user, api]", + "description": "Priority 2: Role to remove", "name": "remove-role", "in": "formData" }, @@ -761,7 +775,7 @@ ], "responses": { "200": { - "description": "Task successful", + "description": "Success Response Message", "schema": { "type": "string" } @@ -769,31 +783,31 @@ "400": { "description": "Bad Request", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "401": { "description": "Unauthorized", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "403": { "description": "Forbidden", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "422": { "description": "Unprocessable Entity: The user could not be updated", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } } } @@ -807,9 +821,6 @@ } ], "description": "Returns a JSON-encoded list of users.\nRequired query-parameter defines if all users or only users with additional special roles are returned.", - "consumes": [ - "application/json" - ], "produces": [ "application/json" ], @@ -828,33 +839,36 @@ ], "responses": { "200": { - "description": "Users returned successfully", + "description": "List of users returned successfully", "schema": { - "type": "string" + "type": "array", + "items": { + "$ref": "#/definitions/api.ApiReturnedUser" + } } }, "400": { "description": "Bad Request", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "401": { "description": "Unauthorized", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "403": { "description": "Forbidden", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } } } @@ -892,8 +906,15 @@ "required": true }, { + "enum": [ + "admin", + "support", + "manager", + "user", + "api" + ], "type": "string", - "description": "User role, one of: [admin, support, manager, user, api]", + "description": "User role", "name": "role", "in": "formData", "required": true @@ -919,7 +940,7 @@ ], "responses": { "200": { - "description": "User added successfully", + "description": "Success Response", "schema": { "type": "string" } @@ -927,31 +948,31 @@ "400": { "description": "Bad Request", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "401": { "description": "Unauthorized", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "403": { "description": "Forbidden", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "422": { "description": "Unprocessable Entity: creating user failed", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } } } @@ -966,6 +987,9 @@ "consumes": [ "multipart/form-data" ], + "produces": [ + "text/plain" + ], "tags": [ "remove" ], @@ -986,31 +1010,31 @@ "400": { "description": "Bad Request", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "401": { "description": "Unauthorized", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "403": { "description": "Forbidden", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "422": { "description": "Unprocessable Entity: deleting user failed", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } } } @@ -1018,6 +1042,32 @@ } }, "definitions": { + "api.ApiReturnedUser": { + "type": "object", + "properties": { + "email": { + "type": "string" + }, + "name": { + "type": "string" + }, + "projects": { + "type": "array", + "items": { + "type": "string" + } + }, + "roles": { + "type": "array", + "items": { + "type": "string" + } + }, + "username": { + "type": "string" + } + } + }, "api.ApiTag": { "type": "object", "properties": { diff --git a/api/swagger.yaml b/api/swagger.yaml index d19f79b..2ba47a0 100644 --- a/api/swagger.yaml +++ b/api/swagger.yaml @@ -1,5 +1,22 @@ basePath: /api definitions: + api.ApiReturnedUser: + properties: + email: + type: string + name: + type: string + projects: + items: + type: string + type: array + roles: + items: + type: string + type: array + username: + type: string + type: object api.ApiTag: properties: name: @@ -1007,13 +1024,23 @@ paths: name: id required: true type: string - - description: 'Priority 1: Role to add, one of: [admin, support, manager, user, - api]' + - description: 'Priority 1: Role to add' + enum: + - admin + - support + - manager + - user + - api in: formData name: add-role type: string - - description: 'Priority 2: Role to remove, one of: [admin, support, manager, - user, api]' + - description: 'Priority 2: Role to remove' + enum: + - admin + - support + - manager + - user + - api in: formData name: remove-role type: string @@ -1029,29 +1056,29 @@ paths: - text/plain responses: "200": - description: Task successful + description: Success Response Message schema: type: string "400": description: Bad Request schema: - $ref: '#/definitions/api.ErrorResponse' + type: string "401": description: Unauthorized schema: - $ref: '#/definitions/api.ErrorResponse' + type: string "403": description: Forbidden schema: - $ref: '#/definitions/api.ErrorResponse' + type: string "422": description: 'Unprocessable Entity: The user could not be updated' schema: - $ref: '#/definitions/api.ErrorResponse' + type: string "500": description: Internal Server Error schema: - $ref: '#/definitions/api.ErrorResponse' + type: string security: - ApiKeyAuth: [] summary: Updates an existing user @@ -1068,37 +1095,37 @@ paths: name: username required: true type: string + produces: + - text/plain responses: "200": description: User deleted successfully "400": description: Bad Request schema: - $ref: '#/definitions/api.ErrorResponse' + type: string "401": description: Unauthorized schema: - $ref: '#/definitions/api.ErrorResponse' + type: string "403": description: Forbidden schema: - $ref: '#/definitions/api.ErrorResponse' + type: string "422": description: 'Unprocessable Entity: deleting user failed' schema: - $ref: '#/definitions/api.ErrorResponse' + type: string "500": description: Internal Server Error schema: - $ref: '#/definitions/api.ErrorResponse' + type: string security: - ApiKeyAuth: [] summary: Deletes a user tags: - remove get: - consumes: - - application/json description: |- Returns a JSON-encoded list of users. Required query-parameter defines if all users or only users with additional special roles are returned. @@ -1113,25 +1140,27 @@ paths: - application/json responses: "200": - description: Users returned successfully + description: List of users returned successfully schema: - type: string + items: + $ref: '#/definitions/api.ApiReturnedUser' + type: array "400": description: Bad Request schema: - $ref: '#/definitions/api.ErrorResponse' + type: string "401": description: Unauthorized schema: - $ref: '#/definitions/api.ErrorResponse' + type: string "403": description: Forbidden schema: - $ref: '#/definitions/api.ErrorResponse' + type: string "500": description: Internal Server Error schema: - $ref: '#/definitions/api.ErrorResponse' + type: string security: - ApiKeyAuth: [] summary: Returns a list of users @@ -1152,7 +1181,13 @@ paths: name: password required: true type: string - - description: 'User role, one of: [admin, support, manager, user, api]' + - description: User role + enum: + - admin + - support + - manager + - user + - api in: formData name: role required: true @@ -1173,29 +1208,29 @@ paths: - text/plain responses: "200": - description: User added successfully + description: Success Response schema: type: string "400": description: Bad Request schema: - $ref: '#/definitions/api.ErrorResponse' + type: string "401": description: Unauthorized schema: - $ref: '#/definitions/api.ErrorResponse' + type: string "403": description: Forbidden schema: - $ref: '#/definitions/api.ErrorResponse' + type: string "422": description: 'Unprocessable Entity: creating user failed' schema: - $ref: '#/definitions/api.ErrorResponse' + type: string "500": description: Internal Server Error schema: - $ref: '#/definitions/api.ErrorResponse' + type: string security: - ApiKeyAuth: [] summary: Adds a new user diff --git a/internal/api/docs.go b/internal/api/docs.go index 4f161e6..f3bcf5e 100644 --- a/internal/api/docs.go +++ b/internal/api/docs.go @@ -741,14 +741,28 @@ const docTemplate = `{ "required": true }, { + "enum": [ + "admin", + "support", + "manager", + "user", + "api" + ], "type": "string", - "description": "Priority 1: Role to add, one of: [admin, support, manager, user, api]", + "description": "Priority 1: Role to add", "name": "add-role", "in": "formData" }, { + "enum": [ + "admin", + "support", + "manager", + "user", + "api" + ], "type": "string", - "description": "Priority 2: Role to remove, one of: [admin, support, manager, user, api]", + "description": "Priority 2: Role to remove", "name": "remove-role", "in": "formData" }, @@ -767,7 +781,7 @@ const docTemplate = `{ ], "responses": { "200": { - "description": "Task successful", + "description": "Success Response Message", "schema": { "type": "string" } @@ -775,31 +789,31 @@ const docTemplate = `{ "400": { "description": "Bad Request", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "401": { "description": "Unauthorized", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "403": { "description": "Forbidden", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "422": { "description": "Unprocessable Entity: The user could not be updated", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } } } @@ -813,9 +827,6 @@ const docTemplate = `{ } ], "description": "Returns a JSON-encoded list of users.\nRequired query-parameter defines if all users or only users with additional special roles are returned.", - "consumes": [ - "application/json" - ], "produces": [ "application/json" ], @@ -834,33 +845,36 @@ const docTemplate = `{ ], "responses": { "200": { - "description": "Users returned successfully", + "description": "List of users returned successfully", "schema": { - "type": "string" + "type": "array", + "items": { + "$ref": "#/definitions/api.ApiReturnedUser" + } } }, "400": { "description": "Bad Request", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "401": { "description": "Unauthorized", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "403": { "description": "Forbidden", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } } } @@ -898,8 +912,15 @@ const docTemplate = `{ "required": true }, { + "enum": [ + "admin", + "support", + "manager", + "user", + "api" + ], "type": "string", - "description": "User role, one of: [admin, support, manager, user, api]", + "description": "User role", "name": "role", "in": "formData", "required": true @@ -925,7 +946,7 @@ const docTemplate = `{ ], "responses": { "200": { - "description": "User added successfully", + "description": "Success Response", "schema": { "type": "string" } @@ -933,31 +954,31 @@ const docTemplate = `{ "400": { "description": "Bad Request", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "401": { "description": "Unauthorized", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "403": { "description": "Forbidden", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "422": { "description": "Unprocessable Entity: creating user failed", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } } } @@ -972,6 +993,9 @@ const docTemplate = `{ "consumes": [ "multipart/form-data" ], + "produces": [ + "text/plain" + ], "tags": [ "remove" ], @@ -992,31 +1016,31 @@ const docTemplate = `{ "400": { "description": "Bad Request", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "401": { "description": "Unauthorized", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "403": { "description": "Forbidden", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "422": { "description": "Unprocessable Entity: deleting user failed", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { - "$ref": "#/definitions/api.ErrorResponse" + "type": "string" } } } @@ -1024,6 +1048,32 @@ const docTemplate = `{ } }, "definitions": { + "api.ApiReturnedUser": { + "type": "object", + "properties": { + "email": { + "type": "string" + }, + "name": { + "type": "string" + }, + "projects": { + "type": "array", + "items": { + "type": "string" + } + }, + "roles": { + "type": "array", + "items": { + "type": "string" + } + }, + "username": { + "type": "string" + } + } + }, "api.ApiTag": { "type": "object", "properties": { diff --git a/internal/api/rest.go b/internal/api/rest.go index 67e4dbe..0d4ddb4 100644 --- a/internal/api/rest.go +++ b/internal/api/rest.go @@ -163,6 +163,14 @@ type JobMetricWithName struct { Metric *schema.JobMetric `json:"metric"` } +type ApiReturnedUser struct { + Username string `json:"username"` + Name string `json:"name"` + Roles []string `json:"roles"` + Email string `json:"email"` + Projects []string `json:"projects"` +} + func handleError(err error, statusCode int, rw http.ResponseWriter) { log.Warnf("REST ERROR : %s", err.Error()) rw.Header().Add("Content-Type", "application/json") @@ -953,16 +961,16 @@ func (api *RestApi) getJobMetrics(rw http.ResponseWriter, r *http.Request) { // @produce plain // @param username formData string true "Unique user ID" // @param password formData string true "User password" -// @param role formData string true "User role, one of: [admin, support, manager, user, api]" +// @param role formData string true "User role" Enums(admin, support, manager, user, api) // @param project formData string false "Managed project, required for new manager role user" // @param name formData string false "Users name" // @param email formData string false "Users email" -// @success 200 {string} string "User added successfully" -// @failure 400 {object} api.ErrorResponse "Bad Request" -// @failure 401 {object} api.ErrorResponse "Unauthorized" -// @failure 403 {object} api.ErrorResponse "Forbidden" -// @failure 422 {object} api.ErrorResponse "Unprocessable Entity: creating user failed" -// @failure 500 {object} api.ErrorResponse "Internal Server Error" +// @success 200 {string} string "Success Response" +// @failure 400 {string} string "Bad Request" +// @failure 401 {string} string "Unauthorized" +// @failure 403 {string} string "Forbidden" +// @failure 422 {string} string "Unprocessable Entity: creating user failed" +// @failure 500 {string} string "Internal Server Error" // @security ApiKeyAuth // @router /users/ [post] func (api *RestApi) createUser(rw http.ResponseWriter, r *http.Request) { @@ -1017,13 +1025,14 @@ func (api *RestApi) createUser(rw http.ResponseWriter, r *http.Request) { // @tags remove // @description User defined by username in form data will be deleted from database. // @accept mpfd -// @param username formData string true "User ID to delete" +// @produce plain +// @param username formData string true "User ID to delete" // @success 200 "User deleted successfully" -// @failure 400 {object} api.ErrorResponse "Bad Request" -// @failure 401 {object} api.ErrorResponse "Unauthorized" -// @failure 403 {object} api.ErrorResponse "Forbidden" -// @failure 422 {object} api.ErrorResponse "Unprocessable Entity: deleting user failed" -// @failure 500 {object} api.ErrorResponse "Internal Server Error" +// @failure 400 {string} string "Bad Request" +// @failure 401 {string} string "Unauthorized" +// @failure 403 {string} string "Forbidden" +// @failure 422 {string} string "Unprocessable Entity: deleting user failed" +// @failure 500 {string} string "Internal Server Error" // @security ApiKeyAuth // @router /users/ [delete] func (api *RestApi) deleteUser(rw http.ResponseWriter, r *http.Request) { @@ -1052,14 +1061,13 @@ func (api *RestApi) deleteUser(rw http.ResponseWriter, r *http.Request) { // @tags query // @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. -// @accept json // @produce json // @param not-just-user query bool true "If returned list should contain all users or only users with additional special roles" -// @success 200 {string} json "Users returned successfully" -// @failure 400 {object} api.ErrorResponse "Bad Request" -// @failure 401 {object} api.ErrorResponse "Unauthorized" -// @failure 403 {object} api.ErrorResponse "Forbidden" -// @failure 500 {object} api.ErrorResponse "Internal Server Error" +// @success 200 {array} api.ApiReturnedUser "List of users returned successfully" +// @failure 400 {string} string "Bad Request" +// @failure 401 {string} string "Unauthorized" +// @failure 403 {string} string "Forbidden" +// @failure 500 {string} string "Internal Server Error" // @security ApiKeyAuth // @router /users/ [get] func (api *RestApi) getUsers(rw http.ResponseWriter, r *http.Request) { @@ -1090,17 +1098,17 @@ func (api *RestApi) getUsers(rw http.ResponseWriter, r *http.Request) { // @description If more than one formValue is set then only the highest priority field is used. // @accept mpfd // @produce plain -// @param id path string true "Database ID of User" -// @param add-role formData string false "Priority 1: Role to add, one of: [admin, support, manager, user, api]" -// @param remove-role formData string false "Priority 2: Role to remove, one of: [admin, support, manager, user, api]" -// @param add-project formData string false "Priority 3: Project to add" -// @param remove-project formData string false "Priority 4: Project to remove" -// @success 200 {string} string "Task successful" -// @failure 400 {object} api.ErrorResponse "Bad Request" -// @failure 401 {object} api.ErrorResponse "Unauthorized" -// @failure 403 {object} api.ErrorResponse "Forbidden" -// @failure 422 {object} api.ErrorResponse "Unprocessable Entity: The user could not be updated" -// @failure 500 {object} api.ErrorResponse "Internal Server Error" +// @param id path string true "Database ID of User" +// @param add-role formData string false "Priority 1: Role to add" Enums(admin, support, manager, user, api) +// @param remove-role formData string false "Priority 2: Role to remove" Enums(admin, support, manager, user, api) +// @param add-project formData string false "Priority 3: Project to add" +// @param remove-project formData string false "Priority 4: Project to remove" +// @success 200 {string} string "Success Response Message" +// @failure 400 {string} string "Bad Request" +// @failure 401 {string} string "Unauthorized" +// @failure 403 {string} string "Forbidden" +// @failure 422 {string} string "Unprocessable Entity: The user could not be updated" +// @failure 500 {string} string "Internal Server Error" // @security ApiKeyAuth // @router /user/{id} [post] func (api *RestApi) updateUser(rw http.ResponseWriter, r *http.Request) {