SMQ-3303 - Update API schema request bodies (#3309)

Signed-off-by: Felix Gateru <felix.gateru@gmail.com>

.github/workflows/api-tests.yaml

@@ -149,7 +149,7 @@ jobs:
           schema: apidocs/openapi/users.yaml
           base-url: ${{ env.USERS_URL }}
           checks: all
-          args: '--header "Authorization: Bearer ${{ env.USER_TOKEN }}" --suppress-health-check=filter_too_much --exclude-checks=positive_data_acceptance --exclude-operation-id=requestPasswordReset --phases=examples,stateful'
+          args: '--header "Authorization: Bearer ${{ env.USER_TOKEN }}" --suppress-health-check=filter_too_much --exclude-checks=positive_data_acceptance --exclude-operation-id=requestPasswordReset --phases=examples'
 
       - name: Run Groups API tests
         if: steps.changes.outputs.groups == 'true' || steps.changes.outputs.workflow == 'true'

apidocs/openapi/auth.yaml

@@ -81,6 +81,8 @@ paths:
           description: Missing or invalid access token provided.
         "404":
           description: A non-existent entity request.
+        "422":
+          description: Service can't process request.
         "500":
           $ref: "#/components/responses/ServiceError"
 
@@ -100,6 +102,8 @@ paths:
           description: Missing or invalid access token provided.
         "404":
           description: A non-existent entity request.
+        "422":
+          description: Service can't process request.
         "500":
           $ref: "#/components/responses/ServiceError"
 
@@ -124,7 +128,7 @@ paths:
           description: Missing or invalid content type.
         "500":
           $ref: "#/components/responses/ServiceError"
-    
+
     get:
       operationId: listPATs
       tags:
@@ -144,7 +148,7 @@ paths:
           description: Missing or invalid access token provided.
         "500":
           $ref: "#/components/responses/ServiceError"
-    
+
     delete:
       operationId: clearAllPATs
       tags:
@@ -159,7 +163,7 @@ paths:
           description: Missing or invalid access token provided.
         "500":
           $ref: "#/components/responses/ServiceError"
-  
+
   /pats/{patID}:
     get:
       operationId: retrievePAT
@@ -181,7 +185,7 @@ paths:
           description: PAT not found.
         "500":
           $ref: "#/components/responses/ServiceError"
-    
+
     delete:
       operationId: deletePAT
       tags:
@@ -200,7 +204,7 @@ paths:
           description: PAT not found.
         "500":
           $ref: "#/components/responses/ServiceError"
-  
+
   /pats/{patID}/name:
     patch:
       operationId: updatePATName
@@ -226,7 +230,7 @@ paths:
           description: Missing or invalid content type.
         "500":
           $ref: "#/components/responses/ServiceError"
-  
+
   /pats/{patID}/description:
     patch:
       operationId: updatePATDescription
@@ -252,7 +256,7 @@ paths:
           description: Missing or invalid content type.
         "500":
           $ref: "#/components/responses/ServiceError"
-  
+
   /pats/{patID}/secret/reset:
     patch:
       operationId: resetPATSecret
@@ -278,7 +282,7 @@ paths:
           description: Missing or invalid content type.
         "500":
           $ref: "#/components/responses/ServiceError"
-  
+
   /pats/{patID}/secret/revoke:
     patch:
       operationId: revokePATSecret
@@ -298,7 +302,7 @@ paths:
           description: PAT not found.
         "500":
           $ref: "#/components/responses/ServiceError"
-  
+
   /pats/{patID}/scope:
     get:
       operationId: listScopes
@@ -322,7 +326,7 @@ paths:
           description: PAT not found.
         "500":
           $ref: "#/components/responses/ServiceError"
-    
+
     delete:
       operationId: clearAllScopes
       tags:
@@ -341,7 +345,7 @@ paths:
           description: PAT not found.
         "500":
           $ref: "#/components/responses/ServiceError"
-  
+
   /pats/{patID}/scope/add:
     patch:
       operationId: addScope
@@ -369,7 +373,7 @@ paths:
           description: Database cannot process the request.
         "500":
           $ref: "#/components/responses/ServiceError"
-  
+
   /pats/{patID}/scope/remove:
     patch:
       operationId: removeScope
@@ -396,7 +400,6 @@ paths:
         "500":
           $ref: "#/components/responses/ServiceError"
 
-
   /health:
     get:
       summary: Retrieves service health check info.
@@ -465,7 +468,7 @@ components:
           format: date-time
           example: "2019-11-26T13:31:52Z"
           description: Time when the PAT was revoked
-    
+
     PATsPage:
       type: object
       properties:
@@ -486,20 +489,10 @@ components:
           items:
             $ref: "#/components/schemas/PAT"
           description: List of Personal Access Tokens
-    
+
     Scope:
       type: object
       properties:
-        id:
-          type: string
-          format: uuid
-          example: "c5747f2f-2a7c-4fe1-b41a-51a5ae290945"
-          description: Scope unique identifier
-        pat_id:
-          type: string
-          format: uuid
-          example: "9118de62-c680-46b7-ad0a-21748a52833a"
-          description: PAT ID this scope belongs to
         optional_domain_id:
           type: string
           format: uuid
@@ -507,7 +500,8 @@ components:
           description: Optional domain ID for the scope
         entity_type:
           type: string
-          enum: [groups, channels, clients, domains, users, dashboards, messages]
+          enum:
+            [groups, channels, clients, domains, users, dashboards, messages]
           example: "groups"
           description: Type of entity the scope applies to
         entity_id:
@@ -516,10 +510,21 @@ components:
           description: ID of the entity the scope applies to. '*' means all entities of the specified type.
         operation:
           type: string
-          enum: [create, read, list, update, delete, share, unshare, publish, subscribe]
+          enum:
+            [
+              create,
+              read,
+              list,
+              update,
+              delete,
+              share,
+              unshare,
+              publish,
+              subscribe,
+            ]
           example: "read"
           description: Operation allowed by this scope
-    
+
     ScopesPage:
       type: object
       properties:
@@ -679,9 +684,11 @@ components:
             type: object
             required:
               - name
+              - duration
             properties:
               name:
                 type: string
+                minLength: 1
                 example: "My PAT"
                 description: Name of the Personal Access Token
               description:
@@ -690,9 +697,10 @@ components:
                 description: Description of the Personal Access Token
               duration:
                 type: string
+                pattern: "^[0-9]+(ns|us|µs|ms|s|m|h|d|w|y)$"
                 example: "30d"
                 description: Duration for which the PAT is valid. Format is a duration string (e.g. "30d", "24h", "1y").
-    
+
     UpdatePATNameRequest:
       description: JSON-formatted document describing PAT name update request.
       required: true
@@ -707,7 +715,7 @@ components:
                 type: string
                 example: "New PAT Name"
                 description: New name for the Personal Access Token
-    
+
     UpdatePATDescriptionRequest:
       description: JSON-formatted document describing PAT description update request.
       required: true
@@ -722,7 +730,7 @@ components:
                 type: string
                 example: "New PAT Description"
                 description: New description for the Personal Access Token
-    
+
     ResetPATSecretRequest:
       description: JSON-formatted document describing PAT secret reset request.
       required: true
@@ -730,12 +738,15 @@ components:
         application/json:
           schema:
             type: object
+            required:
+              - duration
             properties:
               duration:
                 type: string
+                pattern: "^[0-9]+(ns|us|µs|ms|s|m|h|d|w|y)$"
                 example: "30d"
                 description: Duration for which the new PAT secret is valid. Format is a duration string (e.g. "30d", "24h", "1y").
-    
+
     AddScopeRequest:
       description: JSON-formatted document describing add scope request.
       required: true
@@ -751,7 +762,7 @@ components:
                 items:
                   $ref: "#/components/schemas/Scope"
                 description: List of scopes to add
-    
+
     RemoveScopeRequest:
       description: JSON-formatted document describing remove scope request.
       required: true
@@ -793,14 +804,14 @@ components:
         application/json:
           schema:
             $ref: "#/components/schemas/PAT"
-    
+
     PATsPageRes:
       description: Page of Personal Access Tokens.
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/PATsPage"
-    
+
     ScopesPageRes:
       description: Page of scopes.
       content:

apidocs/openapi/channels.yaml

@@ -656,9 +656,7 @@ components:
           example: 10
           description: Maximum number of items to return in one page.
       required:
-        - channels
         - total
-        - offset
 
     ChannelUpdate:
       type: object
@@ -705,7 +703,10 @@ components:
           type: array
           description: Connection types.
           items:
-            example: publish
+            type: string
+            enum:
+              - publish
+              - subscribe
 
     ChannelConnectionReqSchema:
       type: object
@@ -719,7 +720,10 @@ components:
           type: array
           description: Connection types.
           items:
-            example: publish
+            type: string
+            enum:
+              - publish
+              - subscribe
 
     Error:
       type: object
@@ -831,7 +835,6 @@ components:
       in: query
       schema:
         type: string
-        minimum: 0
       required: false
 
     Limit:
@@ -844,7 +847,7 @@ components:
         maximum: 100
         minimum: 1
       required: false
-      example: "100"
+      example: 100
 
     Offset:
       name: offset
@@ -855,8 +858,8 @@ components:
         default: 0
         minimum: 0
       required: false
-      example: "0"
-    
+      example: 0
+
     Order:
       name: order
       description: Field by which to order the results

apidocs/openapi/clients.yaml

@@ -1282,7 +1282,6 @@ components:
       in: query
       schema:
         type: string
-        minimum: 0
       required: false
 
     Limit:
@@ -1295,7 +1294,7 @@ components:
         maximum: 100
         minimum: 1
       required: false
-      example: "100"
+      example: 100
 
     Offset:
       name: offset
@@ -1306,7 +1305,7 @@ components:
         default: 0
         minimum: 0
       required: false
-      example: "0"
+      example: 0
 
     Order:
       name: order

apidocs/openapi/groups.yaml

@@ -96,12 +96,12 @@ paths:
         - $ref: "#/components/parameters/GroupName"
         - $ref: "#/components/parameters/RootGroup"
         - $ref: "#/components/parameters/Status"
-        - $ref: "#/components/parameters/ID" 
+        - $ref: "#/components/parameters/ID"
         - $ref: "./schemas/roles.yaml#/components/parameters/ActionsQuery"
         - $ref: "./schemas/roles.yaml#/components/parameters/RoleIDQuery"
         - $ref: "./schemas/roles.yaml#/components/parameters/RoleNameQuery"
         - $ref: "#/components/parameters/AccessType"
-        - $ref: "#/components/parameters/OnlyTotal" 
+        - $ref: "#/components/parameters/OnlyTotal"
       responses:
         "200":
           $ref: "#/components/responses/GroupPageRes"
@@ -362,6 +362,11 @@ paths:
       responses:
         "200":
           description: Parent group set.
+          content:
+            application/json:
+              schema:
+                type: object
+          links: {}
         "400":
           description: Failed due to malformed group's ID.
         "401":
@@ -392,6 +397,11 @@ paths:
       responses:
         "200":
           description: Parent group removed.
+          content:
+            application/json:
+              schema:
+                type: object
+          links: {}
         "400":
           description: Failed due to malformed group's ID.
         "401":
@@ -1513,7 +1523,6 @@ components:
       in: query
       schema:
         type: string
-        minimum: 0
       required: false
 
     Limit:
@@ -1526,7 +1535,7 @@ components:
         maximum: 100
         minimum: 1
       required: false
-      example: "100"
+      example: 100
 
     Offset:
       name: offset
@@ -1537,9 +1546,9 @@ components:
         default: 0
         minimum: 0
       required: false
-      example: "0"
-    
-    Order: 
+      example: 0
+
+    Order:
       name: order
       description: Field by which to order the results
       in: query
@@ -1547,8 +1556,8 @@ components:
         type: string
       required: false
       example: created_at
-    
-    DirectionOrder: 
+
+    DirectionOrder:
       name: order
       description: Direction of ordering the results.
       in: query
@@ -1560,7 +1569,7 @@ components:
       required: false
       example: desc
 
-    ID: 
+    ID:
       name: id
       description: List groups with the given ID.
       in: query
@@ -1569,7 +1578,7 @@ components:
         format: uuid
       required: false
       example: bb7edb32-2eac-4aad-aebe-ed96fe073879
-    
+
     AccessType:
       name: access_type
       description: Type of access the user has on the group.
@@ -1583,8 +1592,8 @@ components:
           - indirect_group
       required: false
       example: direct
-    
-    OnlyTotal: 
+
+    OnlyTotal:
       name: only_total
       description: If true, the response will contain only the total number of groups that match the query parameters.
       in: query
@@ -1592,7 +1601,7 @@ components:
         type: boolean
         default: false
       required: false
-    
+
     User:
       name: user
       description: If provided lists groups associated with a user with the provided ID. Only available for admin users.
@@ -1663,10 +1672,10 @@ components:
           operationId: getGroup
           parameters:
             groupID: $response.body#/id
-        get_children:
-          operationId: listChildrenGroups
-          parameters:
-            groupID: $response.body#/id
+        # get_children:
+        #   operationId: listChildrenGroups
+        #   parameters:
+        #     groupID: $response.body#/id
         update:
           operationId: updateGroup
           parameters:
@@ -1710,6 +1719,7 @@ components:
         application/json:
           schema:
             $ref: "#/components/schemas/GroupsPage"
+      links: {}
 
     GroupsHierarchyPageRes:
       description: Group hierarchy retrieved.
@@ -1717,6 +1727,7 @@ components:
         application/json:
           schema:
             $ref: "#/components/schemas/GroupsHierarchyPage"
+      links: {}
 
     MembersPageRes:
       description: Group members retrieved.
@@ -1724,6 +1735,7 @@ components:
         application/json:
           schema:
             $ref: "#/components/schemas/MembersPage"
+      links: {}
 
     HealthRes:
       description: Service Health Check.

apidocs/openapi/journal.yaml

@@ -75,7 +75,7 @@ paths:
         This includes connection status, messages sent/received, and other metrics.
       parameters:
         - $ref: "#/components/parameters/domain_id"
-        - $ref: '#/components/parameters/client_id'
+        - $ref: "#/components/parameters/client_id"
       security:
         - bearerAuth: []
       responses:
@@ -319,7 +319,7 @@ components:
         default: 0
         minimum: 0
       required: false
-      example: "0"
+      example: 0
 
     limit:
       name: limit
@@ -328,10 +328,10 @@ components:
       schema:
         type: integer
         default: 10
-        maximum: 10
+        maximum: 100
         minimum: 1
       required: false
-      example: "10"
+      example: 10
 
     operation:
       name: operation
@@ -365,7 +365,7 @@ components:
       description: Start date in unix time.
       in: query
       schema:
-        type: string
+        type: integer
         format: int64
       required: false
       example: 1966777289
@@ -375,7 +375,7 @@ components:
       description: End date in unix time.
       in: query
       schema:
-        type: string
+        type: integer
         format: int64
       required: false
       example: 1966777289

apidocs/openapi/users.yaml

@@ -116,7 +116,7 @@ paths:
         - bearerAuth: []
       responses:
         "200":
-          $ref: "#/components/responses/UserRes"
+          $ref: "#/components/responses/UserProfileRes"
         "400":
           description: Failed due to malformed query parameters.
         "401":
@@ -461,7 +461,7 @@ paths:
         - bearerAuth: []
       responses:
         "200":
-          $ref: "#/components/responses/UserRes"
+          $ref: "#/components/responses/UserProfileRes"
         "400":
           description: Failed due to malformed JSON.
         "401":
@@ -569,7 +569,7 @@ paths:
       requestBody:
         $ref: "#/components/requestBodies/IssueTokenReq"
       responses:
-        "200":
+        "201":
           $ref: "#/components/responses/TokenRes"
         "400":
           description: Failed due to malformed JSON.
@@ -706,7 +706,7 @@ components:
               type: string
               format: password
               example: password
-              minimum: 8
+              minLength: 8
               description: Free-form account secret used for acquiring auth token(s).
           required:
             - username
@@ -830,7 +830,7 @@ components:
             secret:
               type: string
               example: password
-              minimum: 8
+              minLength: 8
               description: User secret password.
         metadata:
           type: object
@@ -895,10 +895,6 @@ components:
           type: object
           example: { "role": "general" }
           description: Arbitrary, object-encoded user's data.
-      required:
-        - first_name
-        - last_name
-        - metadata
 
     UserTags:
       type: object
@@ -908,7 +904,6 @@ components:
           example: ["yello", "orange"]
           description: User tags.
           minItems: 0
-          uniqueItems: true
           items:
             type: string
 
@@ -938,12 +933,12 @@ components:
         old_secret:
           type: string
           example: oldpassword
-          minimum: 8
+          minLength: 8
           description: Old user secret password.
         new_secret:
           type: string
           example: newpassword
-          minimum: 8
+          minLength: 8
           description: New user secret password.
       required:
         - old_secret
@@ -1029,7 +1024,7 @@ components:
         password:
           type: string
           example: password
-          minimum: 8
+          minLength: 8
           description: User secret password.
       required:
         - username
@@ -1278,7 +1273,7 @@ components:
         maximum: 100
         minimum: 1
       required: false
-      example: "100"
+      example: 100
 
     Offset:
       name: offset
@@ -1289,7 +1284,7 @@ components:
         default: 0
         minimum: 0
       required: false
-      example: "0"
+      example: 0
 
     Order:
       name: order
@@ -1444,13 +1439,13 @@ components:
                 format: password
                 description: New password.
                 example: "12345678"
-                minimum: 8
+                minLength: 8
               confirm_password:
                 type: string
                 format: password
                 description: New confirmation password.
                 example: "12345678"
-                minimum: 8
+                minLength: 8
               token:
                 type: string
                 format: jwt
@@ -1467,11 +1462,11 @@ components:
               password:
                 type: string
                 format: password
-                minimum: 8
+                minLength: 8
                 description: New password.
               old_password:
                 type: string
-                minimum: 8
+                minLength: 8
                 format: password
                 description: Old password.
 
@@ -1533,6 +1528,13 @@ components:
           schema:
             $ref: "#/components/schemas/User"
 
+    UserProfileRes:
+      description: Data retrieved for current user profile.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/User"
+
     UserPageRes:
       description: Data retrieved.
       content: