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

packages/backend/src/server/api/endpoints/drive/files/attached-notes.ts

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

packages/backend/src/server/api/endpoints/drive/files/check-existence.ts

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

packages/backend/src/server/api/endpoints/drive/files/create.ts

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

packages/backend/src/server/api/endpoints/drive/files/delete.ts

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

packages/backend/src/server/api/endpoints/drive/files/find-by-hash.ts

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

packages/backend/src/server/api/endpoints/drive/files/find.ts

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

packages/backend/src/server/api/endpoints/drive/files/show.ts

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

packages/backend/src/server/api/endpoints/drive/files/update.ts

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

packages/backend/src/server/api/endpoints/drive/files/upload-from-url.ts

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

packages/backend/src/server/api/endpoints/request-reset-password.ts

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

packages/backend/src/server/api/endpoints/reset-db.ts

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

packages/backend/src/server/api/endpoints/reset-password.ts

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

packages/backend/src/server/api/endpoints/sw/register.ts

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

packages/backend/src/server/api/endpoints/sw/unregister.ts

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

packages/backend/src/server/api/endpoints/test.ts

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

packages/backend/src/server/api/endpoints/users/clips.ts

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

packages/backend/src/server/api/endpoints/users/followers.ts

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

packages/backend/src/server/api/endpoints/users/following.ts

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

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

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

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

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