ClusterCockpit/cc-backend
1
0
Fork 0
mirror of https://github.com/ClusterCockpit/cc-backend synced 2025-07-25 05:36:07 +02:00
Code Issues Packages Releases Activity

Improve user endpoint swagger docs

Browse Source
This commit is contained in:
Christoph Kluge
2023-08-21 12:12:28 +02:00
parent f6c4c963ec
commit f36f62fb47
4 changed files with 261 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
api/swagger.json
View File

@@ -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": {

95
api/swagger.yaml
View File

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