mirror of
https://github.com/NodeBB/NodeBB.git
synced 2026-01-01 21:30:30 +01:00
docs: openapi schema for newly added routes
This commit is contained in:
Julian Lam
@@ -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:
|
||||
|
||||
@@ -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
Normal file
60
public/openapi/write/groups/slug/invites.yaml
Normal 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
Normal file
60
public/openapi/write/groups/slug/pending.yaml
Normal 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
Normal file
66
public/openapi/write/groups/slug/pending/uid.yaml
Normal 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
43
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,
|
||||
|
||||
Reference in New Issue
Block a user