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

* 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
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
49 changed files with 224 additions and 0 deletions

View File

@ -9,6 +9,8 @@ export const meta = {
kind: 'read:drive',
description: 'Find the notes to which the given file is attached.',
res: {
type: 'array',
optional: false, nullable: false,

View File

@ -8,6 +8,8 @@ export const meta = {
kind: 'read:drive',
description: 'Check if a given file exists.',
res: {
type: 'boolean',
optional: false, nullable: false,

View File

@ -20,6 +20,8 @@ export const meta = {
kind: 'write:drive',
description: 'Upload a new drive file.',
res: {
type: 'object',
optional: false, nullable: false,

View File

@ -11,6 +11,8 @@ export const meta = {
kind: 'write:drive',
description: 'Delete an existing drive file.',
errors: {
noSuchFile: {
message: 'No such file.',

View File

@ -8,6 +8,8 @@ export const meta = {
kind: 'read:drive',
description: 'Search for a drive file by a hash of the contents.',
res: {
type: 'array',
optional: false, nullable: false,

View File

@ -9,6 +9,8 @@ export const meta = {
kind: 'read:drive',
description: 'Search for a drive file by the given parameters.',
res: {
type: 'array',
optional: false, nullable: false,

View File

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

View File

@ -11,6 +11,8 @@ export const meta = {
kind: 'write:drive',
description: 'Update the properties of a drive file.',
errors: {
invalidFileName: {
message: 'Invalid file name.',

View File

@ -13,6 +13,8 @@ export const meta = {
max: 60,
},
description: 'Request the server to download a new drive file from the specified URL.',
requireCredential: true,
kind: 'write:drive',

View File

@ -10,8 +10,12 @@ import { genId } from '@/misc/gen-id.js';
import { IsNull } from 'typeorm';
export const meta = {
tags: ['reset password'],
requireCredential: false,
description: 'Request a users password to be reset.',
limit: {
duration: ms('1hour'),
max: 3,

View File

@ -3,8 +3,12 @@ import { ApiError } from '../error.js';
import { resetDb } from '@/db/postgre.js';
export const meta = {
tags: ['non-productive'],
requireCredential: false,
description: 'Only available when running with <code>NODE_ENV=testing</code>. Reset the database and flush Redis.',
errors: {
},

View File

@ -5,8 +5,12 @@ import { Users, UserProfiles, PasswordResetRequests } from '@/models/index.js';
import { ApiError } from '../error.js';
export const meta = {
tags: ['reset password'],
requireCredential: false,
description: 'Complete the password reset that was previously requested.',
errors: {
},

View File

@ -8,6 +8,8 @@ export const meta = {
requireCredential: true,
description: 'Register to receive push notifications.',
res: {
type: 'object',
optional: false, nullable: false,

View File

@ -5,6 +5,8 @@ export const meta = {
tags: ['account'],
requireCredential: true,
description: 'Unregister from receiving push notifications.',
} as const;
export const paramDef = {

View File

@ -1,6 +1,10 @@
import define from '../define.js';
export const meta = {
tags: ['non-productive'],
description: 'Endpoint for testing input validation.',
requireCredential: false,
} as const;

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 = {

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,

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,

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 = {

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,

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,

View File

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

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.',

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.',

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.',

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,

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.',

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,

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.',

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,

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,

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,

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,

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.',

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,

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.',

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.',

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,

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,

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,

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 = {

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,

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,

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

View File

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

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,

View File

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

View File

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

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 = {