hyperzlib
/
nodebb
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: openapi schema for newly added routes

Browse Source
isekai-main
Julian Lam 2 years ago
parent 0788fb5118
commit be3232552b
6 changed files with 298 additions and 1 deletions
Show Stats Download Patch File Download Diff File

64
public/openapi/components/schemas/GroupObject.yaml
Unescape Escape View File

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

6
public/openapi/write.yaml
Unescape Escape View File

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

60
public/openapi/write/groups/slug/invites.yaml
Unescape Escape View File

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

60
public/openapi/write/groups/slug/pending.yaml
Unescape Escape View File

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

66
public/openapi/write/groups/slug/pending/uid.yaml
Unescape Escape View File

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

43
test/api.js
Unescape Escape View File

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

Write Preview
Loading…
Cancel
Save