docs: openapi schema for newly added routes

public/openapi/components/schemas/GroupObject.yaml

@@ -74,8 +74,72 @@ GroupFullObject:
       type: number
     pending:
       type: array
+      items:
+        type: object
+        properties:
+          uid:
+            type: number
+            description: A user identifier
+            example: 1
+          username:
+            type: string
+            description: A friendly name for a given user account
+            example: Dragon Fruit
+          userslug:
+            type: string
+            description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.)
+            example: dragon-fruit
+          picture:
+            type: string
+            description: A URL pointing to a picture to be used as the user's avatar
+            example: 'https://images.unsplash.com/photo-1560070094-e1f2ddec4337?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=256&h=256&q=80'
+            nullable: true
+          displayname:
+            type: string
+            description: This is either username or fullname depending on forum and user settings
+            example: Dragon Fruit
+          'icon:text':
+            type: string
+            description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar
+            example: D
+          'icon:bgColor':
+            type: string
+            description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon
+            example: '#9c27b0'
     invited:
       type: array
+      items:
+        type: object
+        properties:
+          uid:
+            type: number
+            description: A user identifier
+            example: 1
+          username:
+            type: string
+            description: A friendly name for a given user account
+            example: Dragon Fruit
+          userslug:
+            type: string
+            description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.)
+            example: dragon-fruit
+          picture:
+            type: string
+            description: A URL pointing to a picture to be used as the user's avatar
+            example: 'https://images.unsplash.com/photo-1560070094-e1f2ddec4337?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=256&h=256&q=80'
+            nullable: true
+          displayname:
+            type: string
+            description: This is either username or fullname depending on forum and user settings
+            example: Dragon Fruit
+          'icon:text':
+            type: string
+            description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar
+            example: D
+          'icon:bgColor':
+            type: string
+            description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon
+            example: '#9c27b0'
     isMember:
       type: boolean
     isPending:

public/openapi/write.yaml

@@ -96,6 +96,12 @@ paths:
     $ref: 'write/groups/slug/membership/uid.yaml'
   /groups/{slug}/ownership/{uid}:
     $ref: 'write/groups/slug/ownership/uid.yaml'
+  /groups/{slug}/pending:
+    $ref: 'write/groups/slug/pending.yaml'
+  /groups/{slug}/pending/{uid}:
+    $ref: 'write/groups/slug/pending/uid.yaml'
+  /groups/{slug}/invites:
+    $ref: 'write/groups/slug/invites.yaml'
   /categories/:
     $ref: 'write/categories.yaml'
   /categories/{cid}:

public/openapi/write/groups/slug/invites.yaml

@@ -0,0 +1,60 @@
+get:
+  tags:
+    - groups
+  summary: get invited users
+  description: This operation lists users that have been invited to join a specific group
+  parameters:
+    - in: path
+      name: slug
+      schema:
+        type: string
+      required: true
+      description: a group slug
+      example: test-group
+  responses:
+    '200':
+      description: invited users successfully retrieved
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status:
+                $ref: ../../../components/schemas/Status.yaml#/Status
+              response:
+                type: object
+                properties:
+                  invites:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        uid:
+                          type: number
+                          description: A user identifier
+                          example: 1
+                        username:
+                          type: string
+                          description: A friendly name for a given user account
+                          example: Dragon Fruit
+                        userslug:
+                          type: string
+                          description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.)
+                          example: dragon-fruit
+                        picture:
+                          type: string
+                          description: A URL pointing to a picture to be used as the user's avatar
+                          example: 'https://images.unsplash.com/photo-1560070094-e1f2ddec4337?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=256&h=256&q=80'
+                          nullable: true
+                        displayname:
+                          type: string
+                          description: This is either username or fullname depending on forum and user settings
+                          example: Dragon Fruit
+                        'icon:text':
+                          type: string
+                          description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar
+                          example: D
+                        'icon:bgColor':
+                          type: string
+                          description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon
+                          example: '#9c27b0'

public/openapi/write/groups/slug/pending.yaml

@@ -0,0 +1,60 @@
+get:
+  tags:
+    - groups
+  summary: get pending users
+  description: This operation lists users that have requested membership to a specific group
+  parameters:
+    - in: path
+      name: slug
+      schema:
+        type: string
+      required: true
+      description: a group slug
+      example: test-group
+  responses:
+    '200':
+      description: pending users successfully retrieved
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status:
+                $ref: ../../../components/schemas/Status.yaml#/Status
+              response:
+                type: object
+                properties:
+                  pending:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        uid:
+                          type: number
+                          description: A user identifier
+                          example: 1
+                        username:
+                          type: string
+                          description: A friendly name for a given user account
+                          example: Dragon Fruit
+                        userslug:
+                          type: string
+                          description: An URL-safe variant of the username (i.e. lower-cased, spaces removed, etc.)
+                          example: dragon-fruit
+                        picture:
+                          type: string
+                          description: A URL pointing to a picture to be used as the user's avatar
+                          example: 'https://images.unsplash.com/photo-1560070094-e1f2ddec4337?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=256&h=256&q=80'
+                          nullable: true
+                        displayname:
+                          type: string
+                          description: This is either username or fullname depending on forum and user settings
+                          example: Dragon Fruit
+                        'icon:text':
+                          type: string
+                          description: A single-letter representation of a username. This is used in the auto-generated icon given to users without an avatar
+                          example: D
+                        'icon:bgColor':
+                          type: string
+                          description: A six-character hexadecimal colour code assigned to the user. This value is used in conjunction with `icon:text` for the user's auto-generated icon
+                          example: '#9c27b0'

public/openapi/write/groups/slug/pending/uid.yaml

@@ -0,0 +1,66 @@
+put:
+  tags:
+    - group
+  summary: approve pending membership
+  description: This operation approves a pending membership request for a group.
+  parameters:
+    - in: path
+      name: slug
+      schema:
+        type: string
+      required: true
+      description: a group slug
+      example: private-group
+    - in: path
+      name: uid
+      schema:
+        type: number
+      required: true
+      description: a user id
+      example: 2
+  responses:
+    '200':
+      description: Membership request approved.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status:
+                $ref: ../../../../components/schemas/Status.yaml#/Status
+              response:
+                type: object
+                properties: {}
+delete:
+  tags:
+    - group
+  summary: reject pending membership
+  description: This operation rejects a pending membership request for a group.
+  parameters:
+    - in: path
+      name: slug
+      schema:
+        type: string
+      required: true
+      description: a group slug
+      example: private-group
+    - in: path
+      name: uid
+      schema:
+        type: number
+      required: true
+      description: a user id
+      example: 3
+  responses:
+    '200':
+      description: Membership request rejected.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status:
+                $ref: ../../../../components/schemas/Status.yaml#/Status
+              response:
+                type: object
+                properties: {}

test/api.js

@@ -58,7 +58,20 @@ describe('API', async () => {
 			],
 		},
 		post: {},
-		put: {},
+		put: {
+			'/groups/{slug}/pending/{uid}': [
+				{
+					in: 'path',
+					name: 'slug',
+					example: 'private-group',
+				},
+				{
+					in: 'path',
+					name: 'uid',
+					example: '', // to be defined later...
+				},
+			],
+		},
 		delete: {
 			'/users/{uid}/tokens/{token}': [
 				{
@@ -96,6 +109,18 @@ describe('API', async () => {
 					example: '', // to be defined below...
 				},
 			],
+			'/groups/{slug}/pending/{uid}': [
+				{
+					in: 'path',
+					name: 'slug',
+					example: 'private-group',
+				},
+				{
+					in: 'path',
+					name: 'uid',
+					example: '', // to be defined later...
+				},
+			],
 		},
 	};
 
@@ -137,6 +162,22 @@ describe('API', async () => {
 			name: 'Test Group',
 		});
 
+		// Create private groups for pending/invitations
+		const [pending1, pending2, invite1, invite2] = await Promise.all([
+			await user.create({ username: utils.generateUUID().slice(0, 8) }),
+			await user.create({ username: utils.generateUUID().slice(0, 8) }),
+			await user.create({ username: utils.generateUUID().slice(0, 8) }),
+			await user.create({ username: utils.generateUUID().slice(0, 8) }),
+		]);
+		mocks.put['/groups/{slug}/pending/{uid}'][1].example = pending1;
+		mocks.delete['/groups/{slug}/pending/{uid}'][1].example = pending2;
+		await Promise.all(['private-group', 'invitations-only'].map(async (name) => {
+			await groups.create({ name, private: true });
+		}));
+		await groups.requestMembership('private-group', pending1);
+		await groups.requestMembership('private-group', pending2);
+		await groups.invite('invitations-only', [pending1, pending2]);
+
 		await meta.settings.set('core.api', {
 			tokens: [{
 				token: mocks.delete['/users/{uid}/tokens/{token}'][1].example,