sendnrw/misskey
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

enhance: improve documentation for /users/ endpoints (#8790)

Browse Source 
* docs: category & description for reset password

* docs: category & description for testing

* docs: descriptions for groups endpoints

* docs: descriptions for drive file endpoints

* docs: descriptions for sw endpoints

* docs: descriptions for user list endpoints

* docs: descriptions & result type for gallery posts

* docs: descriptions & result type for user endpoints

* docs: add return type for stats
This commit is contained in:
Johann150
2022-06-10 07:25:20 +02:00
committed by GitHub
parent 527f044062
commit 78df3dc484
49 changed files with 224 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
packages/backend/src/server/api/endpoints/users/clips.ts
View File

@@ -4,6 +4,18 @@ import { makePaginationQuery } from '../../common/make-pagination-query.js';
export const meta = {
tags: ['users', 'clips'],
description: 'Show all clips this user owns.',
res: {
type: 'array',
optional: false, nullable: false,
items: {
type: 'object',
optional: false, nullable: false,
ref: 'Clip',
},
},
} as const;
export const paramDef = {

2
packages/backend/src/server/api/endpoints/users/followers.ts
View File

@@ -10,6 +10,8 @@ export const meta = {
requireCredential: false,
description: 'Show everyone that follows this user.',
res: {
type: 'array',
optional: false, nullable: false,

2
packages/backend/src/server/api/endpoints/users/following.ts
View File

@@ -10,6 +10,8 @@ export const meta = {
requireCredential: false,
description: 'Show everyone that this user is following.',
res: {
type: 'array',
optional: false, nullable: false,

12
packages/backend/src/server/api/endpoints/users/gallery/posts.ts
View File

@@ -4,6 +4,18 @@ import { makePaginationQuery } from '../../../common/make-pagination-query.js';
export const meta = {
tags: ['users', 'gallery'],
description: 'Show all gallery posts by the given user.',
res: {
type: 'array',
optional: false, nullable: false,
items: {
type: 'object',
optional: false, nullable: false,
ref: 'GalleryPost',
},
},
} as const;
export const paramDef = {

2
packages/backend/src/server/api/endpoints/users/get-frequently-replied-users.ts
View File

@@ -10,6 +10,8 @@ export const meta = {
requireCredential: false,
description: 'Get a list of other users that the specified user frequently replies to.',
res: {
type: 'array',
optional: false, nullable: false,

2
packages/backend/src/server/api/endpoints/users/groups/create.ts
View File

@@ -11,6 +11,8 @@ export const meta = {
kind: 'write:user-groups',
description: 'Create a new group.',
res: {
type: 'object',
optional: false, nullable: false,

2
packages/backend/src/server/api/endpoints/users/groups/delete.ts
View File

@@ -9,6 +9,8 @@ export const meta = {
kind: 'write:user-groups',
description: 'Delete an existing group.',
errors: {
noSuchGroup: {
message: 'No such group.',

2
packages/backend/src/server/api/endpoints/users/groups/invitations/accept.ts
View File

@@ -11,6 +11,8 @@ export const meta = {
kind: 'write:user-groups',
description: 'Join a group the authenticated user has been invited to.',
errors: {
noSuchInvitation: {
message: 'No such invitation.',

2
packages/backend/src/server/api/endpoints/users/groups/invitations/reject.ts
View File

@@ -9,6 +9,8 @@ export const meta = {
kind: 'write:user-groups',
description: 'Delete an existing group invitation for the authenticated user without joining the group.',
errors: {
noSuchInvitation: {
message: 'No such invitation.',

2
packages/backend/src/server/api/endpoints/users/groups/invite.ts
View File

@@ -13,6 +13,8 @@ export const meta = {
kind: 'write:user-groups',
description: 'Invite a user to an existing group.',
errors: {
noSuchGroup: {
message: 'No such group.',

2
packages/backend/src/server/api/endpoints/users/groups/joined.ts
View File

@@ -9,6 +9,8 @@ export const meta = {
kind: 'read:user-groups',
description: 'List the groups that the authenticated user is a member of.',
res: {
type: 'array',
optional: false, nullable: false,

2
packages/backend/src/server/api/endpoints/users/groups/leave.ts
View File

@@ -9,6 +9,8 @@ export const meta = {
kind: 'write:user-groups',
description: 'Leave a group. The owner of a group can not leave. They must transfer ownership or delete the group instead.',
errors: {
noSuchGroup: {
message: 'No such group.',

2
packages/backend/src/server/api/endpoints/users/groups/owned.ts
View File

@@ -8,6 +8,8 @@ export const meta = {
kind: 'read:user-groups',
description: 'List the groups that the authenticated user is the owner of.',
res: {
type: 'array',
optional: false, nullable: false,

2
packages/backend/src/server/api/endpoints/users/groups/pull.ts
View File

@@ -10,6 +10,8 @@ export const meta = {
kind: 'write:user-groups',
description: 'Removes a specified user from a group. The owner can not be removed.',
errors: {
noSuchGroup: {
message: 'No such group.',

2
packages/backend/src/server/api/endpoints/users/groups/show.ts
View File

@@ -9,6 +9,8 @@ export const meta = {
kind: 'read:user-groups',
description: 'Show the properties of a group.',
res: {
type: 'object',
optional: false, nullable: false,

2
packages/backend/src/server/api/endpoints/users/groups/transfer.ts
View File

@@ -10,6 +10,8 @@ export const meta = {
kind: 'write:user-groups',
description: 'Transfer ownership of a group from the authenticated user to another user.',
res: {
type: 'object',
optional: false, nullable: false,

2
packages/backend/src/server/api/endpoints/users/groups/update.ts
View File

@@ -9,6 +9,8 @@ export const meta = {
kind: 'write:user-groups',
description: 'Update the properties of a group.',
res: {
type: 'object',
optional: false, nullable: false,

2
packages/backend/src/server/api/endpoints/users/lists/create.ts
View File

@@ -10,6 +10,8 @@ export const meta = {
kind: 'write:account',
description: 'Create a new list of users.',
res: {
type: 'object',
optional: false, nullable: false,

2
packages/backend/src/server/api/endpoints/users/lists/delete.ts
View File

@@ -9,6 +9,8 @@ export const meta = {
kind: 'write:account',
description: 'Delete an existing list of users.',
errors: {
noSuchList: {
message: 'No such list.',

2
packages/backend/src/server/api/endpoints/users/lists/list.ts
View File

@@ -8,6 +8,8 @@ export const meta = {
kind: 'read:account',
description: 'Show all lists that the authenticated user has created.',
res: {
type: 'array',
optional: false, nullable: false,

2
packages/backend/src/server/api/endpoints/users/lists/pull.ts
View File

@@ -11,6 +11,8 @@ export const meta = {
kind: 'write:account',
description: 'Remove a user from a list.',
errors: {
noSuchList: {
message: 'No such list.',

2
packages/backend/src/server/api/endpoints/users/lists/push.ts
View File

@@ -11,6 +11,8 @@ export const meta = {
kind: 'write:account',
description: 'Add a user to an existing list.',
errors: {
noSuchList: {
message: 'No such list.',

2
packages/backend/src/server/api/endpoints/users/lists/show.ts
View File

@@ -9,6 +9,8 @@ export const meta = {
kind: 'read:account',
description: 'Show the properties of a list.',
res: {
type: 'object',
optional: false, nullable: false,

2
packages/backend/src/server/api/endpoints/users/lists/update.ts
View File

@@ -9,6 +9,8 @@ export const meta = {
kind: 'write:account',
description: 'Update the properties of a list.',
res: {
type: 'object',
optional: false, nullable: false,

2
packages/backend/src/server/api/endpoints/users/notes.ts
View File

@@ -12,6 +12,8 @@ import { generateMutedInstanceQuery } from '../../common/generate-muted-instance
export const meta = {
tags: ['users', 'notes'],
description: 'Show all notes that this user created.',
res: {
type: 'array',
optional: false, nullable: false,

12
packages/backend/src/server/api/endpoints/users/pages.ts
View File

@@ -4,6 +4,18 @@ import { makePaginationQuery } from '../../common/make-pagination-query.js';
export const meta = {
tags: ['users', 'pages'],
description: 'Show all pages this user created.',
res: {
type: 'array',
optional: false, nullable: false,
items: {
type: 'object',
optional: false, nullable: false,
ref: 'Page',
},
},
} as const;
export const paramDef = {

2
packages/backend/src/server/api/endpoints/users/reactions.ts
View File

@@ -9,6 +9,8 @@ export const meta = {
requireCredential: false,
description: 'Show all reactions this user made.',
res: {
type: 'array',
optional: false, nullable: false,

2
packages/backend/src/server/api/endpoints/users/recommendation.ts
View File

@@ -11,6 +11,8 @@ export const meta = {
kind: 'read:account',
description: 'Show users that the authenticated user might be interested to follow.',
res: {
type: 'array',
optional: false, nullable: false,

2
packages/backend/src/server/api/endpoints/users/relation.ts
View File

@@ -6,6 +6,8 @@ export const meta = {
requireCredential: true,
description: 'Show the different kinds of relations between the authenticated user and the specified user(s).',
res: {
optional: false, nullable: false,
oneOf: [

2
packages/backend/src/server/api/endpoints/users/report-abuse.ts
View File

@@ -13,6 +13,8 @@ export const meta = {
requireCredential: true,
description: 'File a report.',
errors: {
noSuchUser: {
message: 'No such user.',

2
packages/backend/src/server/api/endpoints/users/search-by-username-and-host.ts
View File

@@ -9,6 +9,8 @@ export const meta = {
requireCredential: false,
description: 'Search for a user by username and/or host.',
res: {
type: 'array',
optional: false, nullable: false,

2
packages/backend/src/server/api/endpoints/users/search.ts
View File

@@ -8,6 +8,8 @@ export const meta = {
requireCredential: false,
description: 'Search for users.',
res: {
type: 'array',
optional: false, nullable: false,

2
packages/backend/src/server/api/endpoints/users/show.ts
View File

@@ -11,6 +11,8 @@ export const meta = {
requireCredential: false,
description: 'Show the properties of a user.',
res: {
optional: false, nullable: false,
oneOf: [

90
packages/backend/src/server/api/endpoints/users/stats.ts
View File

@@ -8,6 +8,8 @@ export const meta = {
requireCredential: false,
description: 'Show statistics about a user.',
errors: {
noSuchUser: {
message: 'No such user.',
@@ -15,6 +17,94 @@ export const meta = {
id: '9e638e45-3b25-4ef7-8f95-07e8498f1819',
},
},
res: {
type: 'object',
optional: false, nullable: false,
properties: {
notesCount: {
type: 'integer',
optional: false, nullable: false,
},
repliesCount: {
type: 'integer',
optional: false, nullable: false,
},
renotesCount: {
type: 'integer',
optional: false, nullable: false,
},
repliedCount: {
type: 'integer',
optional: false, nullable: false,
},
renotedCount: {
type: 'integer',
optional: false, nullable: false,
},
pollVotesCount: {
type: 'integer',
optional: false, nullable: false,
},
pollVotedCount: {
type: 'integer',
optional: false, nullable: false,
},
localFollowingCount: {
type: 'integer',
optional: false, nullable: false,
},
remoteFollowingCount: {
type: 'integer',
optional: false, nullable: false,
},
localFollowersCount: {
type: 'integer',
optional: false, nullable: false,
},
remoteFollowersCount: {
type: 'integer',
optional: false, nullable: false,
},
followingCount: {
type: 'integer',
optional: false, nullable: false,
},
followersCount: {
type: 'integer',
optional: false, nullable: false,
},
sentReactionsCount: {
type: 'integer',
optional: false, nullable: false,
},
receivedReactionsCount: {
type: 'integer',
optional: false, nullable: false,
},
noteFavoritesCount: {
type: 'integer',
optional: false, nullable: false,
},
pageLikesCount: {
type: 'integer',
optional: false, nullable: false,
},
pageLikedCount: {
type: 'integer',
optional: false, nullable: false,
},
driveFilesCount: {
type: 'integer',
optional: false, nullable: false,
},
driveUsage: {
type: 'integer',
optional: false, nullable: false,
description: 'Drive usage in bytes',
},
},
},
} as const;
export const paramDef = {