From be3232552b3893bfbfc7fe572db65953df93d163 Mon Sep 17 00:00:00 2001 From: Julian Lam Date: Fri, 31 Mar 2023 12:24:26 -0400 Subject: [PATCH] docs: openapi schema for newly added routes --- .../components/schemas/GroupObject.yaml | 64 ++++++++++++++++++ public/openapi/write.yaml | 6 ++ public/openapi/write/groups/slug/invites.yaml | 60 +++++++++++++++++ public/openapi/write/groups/slug/pending.yaml | 60 +++++++++++++++++ .../write/groups/slug/pending/uid.yaml | 66 +++++++++++++++++++ test/api.js | 43 +++++++++++- 6 files changed, 298 insertions(+), 1 deletion(-) create mode 100644 public/openapi/write/groups/slug/invites.yaml create mode 100644 public/openapi/write/groups/slug/pending.yaml create mode 100644 public/openapi/write/groups/slug/pending/uid.yaml diff --git a/public/openapi/components/schemas/GroupObject.yaml b/public/openapi/components/schemas/GroupObject.yaml index c1b28479d5..99148f249d 100644 --- a/public/openapi/components/schemas/GroupObject.yaml +++ b/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: diff --git a/public/openapi/write.yaml b/public/openapi/write.yaml index d68c2f45cf..995502a515 100644 --- a/public/openapi/write.yaml +++ b/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}: diff --git a/public/openapi/write/groups/slug/invites.yaml b/public/openapi/write/groups/slug/invites.yaml new file mode 100644 index 0000000000..aec049a8a1 --- /dev/null +++ b/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' \ No newline at end of file diff --git a/public/openapi/write/groups/slug/pending.yaml b/public/openapi/write/groups/slug/pending.yaml new file mode 100644 index 0000000000..89a729970a --- /dev/null +++ b/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' \ No newline at end of file diff --git a/public/openapi/write/groups/slug/pending/uid.yaml b/public/openapi/write/groups/slug/pending/uid.yaml new file mode 100644 index 0000000000..3e0182ebce --- /dev/null +++ b/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: {} \ No newline at end of file diff --git a/test/api.js b/test/api.js index ad0b6a5bee..01b8512013 100644 --- a/test/api.js +++ b/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,