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
GitHub
parent
527f044062
commit
78df3dc484
49 changed files with 224 additions and 0 deletions
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -8,6 +8,8 @@ export const meta = {
|
|||
|
||||
kind: 'read:drive',
|
||||
|
||||
description: 'Check if a given file exists.',
|
||||
|
||||
res: {
|
||||
type: 'boolean',
|
||||
optional: false, nullable: false,
|
||||
|
|
|
|||
|
|
@ -20,6 +20,8 @@ export const meta = {
|
|||
|
||||
kind: 'write:drive',
|
||||
|
||||
description: 'Upload a new drive file.',
|
||||
|
||||
res: {
|
||||
type: 'object',
|
||||
optional: false, nullable: false,
|
||||
|
|
|
|||
|
|
@ -11,6 +11,8 @@ export const meta = {
|
|||
|
||||
kind: 'write:drive',
|
||||
|
||||
description: 'Delete an existing drive file.',
|
||||
|
||||
errors: {
|
||||
noSuchFile: {
|
||||
message: 'No such 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,
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -11,6 +11,8 @@ export const meta = {
|
|||
|
||||
kind: 'write:drive',
|
||||
|
||||
description: 'Update the properties of a drive file.',
|
||||
|
||||
errors: {
|
||||
invalidFileName: {
|
||||
message: 'Invalid file name.',
|
||||
|
|
|
|||
|
|
@ -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',
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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: {
|
||||
|
||||
},
|
||||
|
|
|
|||
|
|
@ -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: {
|
||||
|
||||
},
|
||||
|
|
|
|||
|
|
@ -8,6 +8,8 @@ export const meta = {
|
|||
|
||||
requireCredential: true,
|
||||
|
||||
description: 'Register to receive push notifications.',
|
||||
|
||||
res: {
|
||||
type: 'object',
|
||||
optional: false, nullable: false,
|
||||
|
|
|
|||
|
|
@ -5,6 +5,8 @@ export const meta = {
|
|||
tags: ['account'],
|
||||
|
||||
requireCredential: true,
|
||||
|
||||
description: 'Unregister from receiving push notifications.',
|
||||
} as const;
|
||||
|
||||
export const paramDef = {
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
||||
|
|
|
|||
|
|
@ -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 = {
|
||||
|
|
|
|||
|
|
@ -10,6 +10,8 @@ export const meta = {
|
|||
|
||||
requireCredential: false,
|
||||
|
||||
description: 'Show everyone that follows this user.',
|
||||
|
||||
res: {
|
||||
type: 'array',
|
||||
optional: false, nullable: false,
|
||||
|
|
|
|||
|
|
@ -10,6 +10,8 @@ export const meta = {
|
|||
|
||||
requireCredential: false,
|
||||
|
||||
description: 'Show everyone that this user is following.',
|
||||
|
||||
res: {
|
||||
type: 'array',
|
||||
optional: false, nullable: false,
|
||||
|
|
|
|||
|
|
@ -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 = {
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -11,6 +11,8 @@ export const meta = {
|
|||
|
||||
kind: 'write:user-groups',
|
||||
|
||||
description: 'Create a new group.',
|
||||
|
||||
res: {
|
||||
type: 'object',
|
||||
optional: false, nullable: false,
|
||||
|
|
|
|||
|
|
@ -9,6 +9,8 @@ export const meta = {
|
|||
|
||||
kind: 'write:user-groups',
|
||||
|
||||
description: 'Delete an existing group.',
|
||||
|
||||
errors: {
|
||||
noSuchGroup: {
|
||||
message: 'No such group.',
|
||||
|
|
|
|||
|
|
@ -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.',
|
||||
|
|
|
|||
|
|
@ -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.',
|
||||
|
|
|
|||
|
|
@ -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.',
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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.',
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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.',
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -10,6 +10,8 @@ export const meta = {
|
|||
|
||||
kind: 'write:account',
|
||||
|
||||
description: 'Create a new list of users.',
|
||||
|
||||
res: {
|
||||
type: 'object',
|
||||
optional: false, nullable: false,
|
||||
|
|
|
|||
|
|
@ -9,6 +9,8 @@ export const meta = {
|
|||
|
||||
kind: 'write:account',
|
||||
|
||||
description: 'Delete an existing list of users.',
|
||||
|
||||
errors: {
|
||||
noSuchList: {
|
||||
message: 'No such list.',
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -11,6 +11,8 @@ export const meta = {
|
|||
|
||||
kind: 'write:account',
|
||||
|
||||
description: 'Remove a user from a list.',
|
||||
|
||||
errors: {
|
||||
noSuchList: {
|
||||
message: 'No such list.',
|
||||
|
|
|
|||
|
|
@ -11,6 +11,8 @@ export const meta = {
|
|||
|
||||
kind: 'write:account',
|
||||
|
||||
description: 'Add a user to an existing list.',
|
||||
|
||||
errors: {
|
||||
noSuchList: {
|
||||
message: 'No such list.',
|
||||
|
|
|
|||
|
|
@ -9,6 +9,8 @@ export const meta = {
|
|||
|
||||
kind: 'read:account',
|
||||
|
||||
description: 'Show the properties of a list.',
|
||||
|
||||
res: {
|
||||
type: 'object',
|
||||
optional: false, nullable: false,
|
||||
|
|
|
|||
|
|
@ -9,6 +9,8 @@ export const meta = {
|
|||
|
||||
kind: 'write:account',
|
||||
|
||||
description: 'Update the properties of a list.',
|
||||
|
||||
res: {
|
||||
type: 'object',
|
||||
optional: false, nullable: false,
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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 = {
|
||||
|
|
|
|||
|
|
@ -9,6 +9,8 @@ export const meta = {
|
|||
|
||||
requireCredential: false,
|
||||
|
||||
description: 'Show all reactions this user made.',
|
||||
|
||||
res: {
|
||||
type: 'array',
|
||||
optional: false, nullable: false,
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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: [
|
||||
|
|
|
|||
|
|
@ -13,6 +13,8 @@ export const meta = {
|
|||
|
||||
requireCredential: true,
|
||||
|
||||
description: 'File a report.',
|
||||
|
||||
errors: {
|
||||
noSuchUser: {
|
||||
message: 'No such user.',
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -8,6 +8,8 @@ export const meta = {
|
|||
|
||||
requireCredential: false,
|
||||
|
||||
description: 'Search for users.',
|
||||
|
||||
res: {
|
||||
type: 'array',
|
||||
optional: false, nullable: false,
|
||||
|
|
|
|||
|
|
@ -11,6 +11,8 @@ export const meta = {
|
|||
|
||||
requireCredential: false,
|
||||
|
||||
description: 'Show the properties of a user.',
|
||||
|
||||
res: {
|
||||
optional: false, nullable: false,
|
||||
oneOf: [
|
||||
|
|
|
|||
|
|
@ -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 = {
|
||||
|
|
|
|||
Loading…
Reference in a new issue