Improve user endpoint swagger docs

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