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

49 files changed, 224 insertions, 0 deletions

diff --git a/packages/backend/src/server/api/endpoints/drive/files/attached-notes.ts b/packages/backend/src/server/api/endpoints/drive/files/attached-notes.ts
index 7ffe89a1e5..415a8cc693 100644
--- a/packages/backend/src/server/api/endpoints/drive/files/attached-notes.ts
+++ b/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,
diff --git a/packages/backend/src/server/api/endpoints/drive/files/check-existence.ts b/packages/backend/src/server/api/endpoints/drive/files/check-existence.ts
index 80293df5d9..bbae9bf4e4 100644
--- a/packages/backend/src/server/api/endpoints/drive/files/check-existence.ts
+++ b/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,
diff --git a/packages/backend/src/server/api/endpoints/drive/files/create.ts b/packages/backend/src/server/api/endpoints/drive/files/create.ts
index 0939ae3365..7397fd9ce9 100644
--- a/packages/backend/src/server/api/endpoints/drive/files/create.ts
+++ b/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,
diff --git a/packages/backend/src/server/api/endpoints/drive/files/delete.ts b/packages/backend/src/server/api/endpoints/drive/files/delete.ts
index 61c56e6314..6108ae7da9 100644
--- a/packages/backend/src/server/api/endpoints/drive/files/delete.ts
+++ b/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.',
diff --git a/packages/backend/src/server/api/endpoints/drive/files/find-by-hash.ts b/packages/backend/src/server/api/endpoints/drive/files/find-by-hash.ts
index 0b74cb9f01..f2bc7348c6 100644
--- a/packages/backend/src/server/api/endpoints/drive/files/find-by-hash.ts
+++ b/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,
diff --git a/packages/backend/src/server/api/endpoints/drive/files/find.ts b/packages/backend/src/server/api/endpoints/drive/files/find.ts
index 4938a69d11..245fb45a65 100644
--- a/packages/backend/src/server/api/endpoints/drive/files/find.ts
+++ b/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,
diff --git a/packages/backend/src/server/api/endpoints/drive/files/show.ts b/packages/backend/src/server/api/endpoints/drive/files/show.ts
index fb19345fee..2c604c54c8 100644
--- a/packages/backend/src/server/api/endpoints/drive/files/show.ts
+++ b/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,
diff --git a/packages/backend/src/server/api/endpoints/drive/files/update.ts b/packages/backend/src/server/api/endpoints/drive/files/update.ts
index 4b3f5f2dc9..e3debe0b4f 100644
--- a/packages/backend/src/server/api/endpoints/drive/files/update.ts
+++ b/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.',
diff --git a/packages/backend/src/server/api/endpoints/drive/files/upload-from-url.ts b/packages/backend/src/server/api/endpoints/drive/files/upload-from-url.ts
index 3bfecac802..53f2298f21 100644
--- a/packages/backend/src/server/api/endpoints/drive/files/upload-from-url.ts
+++ b/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',
diff --git a/packages/backend/src/server/api/endpoints/request-reset-password.ts b/packages/backend/src/server/api/endpoints/request-reset-password.ts
index 046337f040..12ce7a9834 100644
--- a/packages/backend/src/server/api/endpoints/request-reset-password.ts
+++ b/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,
diff --git a/packages/backend/src/server/api/endpoints/reset-db.ts b/packages/backend/src/server/api/endpoints/reset-db.ts
index dbe64e9a13..5ff115dab5 100644
--- a/packages/backend/src/server/api/endpoints/reset-db.ts
+++ b/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: {
 
 	},
diff --git a/packages/backend/src/server/api/endpoints/reset-password.ts b/packages/backend/src/server/api/endpoints/reset-password.ts
index 7acc545c40..3dcb0b9b83 100644
--- a/packages/backend/src/server/api/endpoints/reset-password.ts
+++ b/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: {
 
 	},
diff --git a/packages/backend/src/server/api/endpoints/sw/register.ts b/packages/backend/src/server/api/endpoints/sw/register.ts
index a48973a0df..5bc3b9b6a1 100644
--- a/packages/backend/src/server/api/endpoints/sw/register.ts
+++ b/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,
diff --git a/packages/backend/src/server/api/endpoints/sw/unregister.ts b/packages/backend/src/server/api/endpoints/sw/unregister.ts
index 9748f2a222..c21856d28f 100644
--- a/packages/backend/src/server/api/endpoints/sw/unregister.ts
+++ b/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 = {
diff --git a/packages/backend/src/server/api/endpoints/test.ts b/packages/backend/src/server/api/endpoints/test.ts
index 256da1a66f..9949237a7e 100644
--- a/packages/backend/src/server/api/endpoints/test.ts
+++ b/packages/backend/src/server/api/endpoints/test.ts
@@ -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;
 
diff --git a/packages/backend/src/server/api/endpoints/users/clips.ts b/packages/backend/src/server/api/endpoints/users/clips.ts
index 424c594749..37d4153950 100644
--- a/packages/backend/src/server/api/endpoints/users/clips.ts
+++ b/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 = {
diff --git a/packages/backend/src/server/api/endpoints/users/followers.ts b/packages/backend/src/server/api/endpoints/users/followers.ts
index 26b1f20df0..b1fb656208 100644
--- a/packages/backend/src/server/api/endpoints/users/followers.ts
+++ b/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,
diff --git a/packages/backend/src/server/api/endpoints/users/following.ts b/packages/backend/src/server/api/endpoints/users/following.ts
index 42cf5216e8..429a5e80e5 100644
--- a/packages/backend/src/server/api/endpoints/users/following.ts
+++ b/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,
diff --git a/packages/backend/src/server/api/endpoints/users/gallery/posts.ts b/packages/backend/src/server/api/endpoints/users/gallery/posts.ts
index d7c435256c..35bf2df598 100644
--- a/packages/backend/src/server/api/endpoints/users/gallery/posts.ts
+++ b/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 = {
diff --git a/packages/backend/src/server/api/endpoints/users/get-frequently-replied-users.ts b/packages/backend/src/server/api/endpoints/users/get-frequently-replied-users.ts
index 73cadc0df7..ab5837b3f3 100644
--- a/packages/backend/src/server/api/endpoints/users/get-frequently-replied-users.ts
+++ b/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,
diff --git a/packages/backend/src/server/api/endpoints/users/groups/create.ts b/packages/backend/src/server/api/endpoints/users/groups/create.ts
index fc775d7cc1..fcaf4af3c3 100644
--- a/packages/backend/src/server/api/endpoints/users/groups/create.ts
+++ b/packages/backend/src/server/api/endpoints/users/groups/create.ts
@@ -11,6 +11,8 @@ export const meta = {
 
 	kind: 'write:user-groups',
 
+	description: 'Create a new group.',
+
 	res: {
 		type: 'object',
 		optional: false, nullable: false,
diff --git a/packages/backend/src/server/api/endpoints/users/groups/delete.ts b/packages/backend/src/server/api/endpoints/users/groups/delete.ts
index f68006994c..1bf253ae3f 100644
--- a/packages/backend/src/server/api/endpoints/users/groups/delete.ts
+++ b/packages/backend/src/server/api/endpoints/users/groups/delete.ts
@@ -9,6 +9,8 @@ export const meta = {
 
 	kind: 'write:user-groups',
 
+	description: 'Delete an existing group.',
+
 	errors: {
 		noSuchGroup: {
 			message: 'No such group.',
diff --git a/packages/backend/src/server/api/endpoints/users/groups/invitations/accept.ts b/packages/backend/src/server/api/endpoints/users/groups/invitations/accept.ts
index 75c1acc302..eafd7f592c 100644
--- a/packages/backend/src/server/api/endpoints/users/groups/invitations/accept.ts
+++ b/packages/backend/src/server/api/endpoints/users/groups/invitations/accept.ts
@@ -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.',
diff --git a/packages/backend/src/server/api/endpoints/users/groups/invitations/reject.ts b/packages/backend/src/server/api/endpoints/users/groups/invitations/reject.ts
index 46bc780ab0..08d3a3804b 100644
--- a/packages/backend/src/server/api/endpoints/users/groups/invitations/reject.ts
+++ b/packages/backend/src/server/api/endpoints/users/groups/invitations/reject.ts
@@ -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.',
diff --git a/packages/backend/src/server/api/endpoints/users/groups/invite.ts b/packages/backend/src/server/api/endpoints/users/groups/invite.ts
index 30a5beb1d9..cc82e43f21 100644
--- a/packages/backend/src/server/api/endpoints/users/groups/invite.ts
+++ b/packages/backend/src/server/api/endpoints/users/groups/invite.ts
@@ -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.',
diff --git a/packages/backend/src/server/api/endpoints/users/groups/joined.ts b/packages/backend/src/server/api/endpoints/users/groups/joined.ts
index 77dc59d3e5..6a2862ee5a 100644
--- a/packages/backend/src/server/api/endpoints/users/groups/joined.ts
+++ b/packages/backend/src/server/api/endpoints/users/groups/joined.ts
@@ -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,
diff --git a/packages/backend/src/server/api/endpoints/users/groups/leave.ts b/packages/backend/src/server/api/endpoints/users/groups/leave.ts
index 33abd5439f..2343cdf857 100644
--- a/packages/backend/src/server/api/endpoints/users/groups/leave.ts
+++ b/packages/backend/src/server/api/endpoints/users/groups/leave.ts
@@ -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.',
diff --git a/packages/backend/src/server/api/endpoints/users/groups/owned.ts b/packages/backend/src/server/api/endpoints/users/groups/owned.ts
index b1289e601f..de030193cc 100644
--- a/packages/backend/src/server/api/endpoints/users/groups/owned.ts
+++ b/packages/backend/src/server/api/endpoints/users/groups/owned.ts
@@ -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,
diff --git a/packages/backend/src/server/api/endpoints/users/groups/pull.ts b/packages/backend/src/server/api/endpoints/users/groups/pull.ts
index b31990b2e3..703dad6d3b 100644
--- a/packages/backend/src/server/api/endpoints/users/groups/pull.ts
+++ b/packages/backend/src/server/api/endpoints/users/groups/pull.ts
@@ -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.',
diff --git a/packages/backend/src/server/api/endpoints/users/groups/show.ts b/packages/backend/src/server/api/endpoints/users/groups/show.ts
index 3ffb0f5ba9..e1cee5fcf7 100644
--- a/packages/backend/src/server/api/endpoints/users/groups/show.ts
+++ b/packages/backend/src/server/api/endpoints/users/groups/show.ts
@@ -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,
diff --git a/packages/backend/src/server/api/endpoints/users/groups/transfer.ts b/packages/backend/src/server/api/endpoints/users/groups/transfer.ts
index 41ceee3b2e..1496e766ca 100644
--- a/packages/backend/src/server/api/endpoints/users/groups/transfer.ts
+++ b/packages/backend/src/server/api/endpoints/users/groups/transfer.ts
@@ -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,
diff --git a/packages/backend/src/server/api/endpoints/users/groups/update.ts b/packages/backend/src/server/api/endpoints/users/groups/update.ts
index 1016aa8926..43cf3e484e 100644
--- a/packages/backend/src/server/api/endpoints/users/groups/update.ts
+++ b/packages/backend/src/server/api/endpoints/users/groups/update.ts
@@ -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,
diff --git a/packages/backend/src/server/api/endpoints/users/lists/create.ts b/packages/backend/src/server/api/endpoints/users/lists/create.ts
index d5260256d5..d2941a0af5 100644
--- a/packages/backend/src/server/api/endpoints/users/lists/create.ts
+++ b/packages/backend/src/server/api/endpoints/users/lists/create.ts
@@ -10,6 +10,8 @@ export const meta = {
 
 	kind: 'write:account',
 
+	description: 'Create a new list of users.',
+
 	res: {
 		type: 'object',
 		optional: false, nullable: false,
diff --git a/packages/backend/src/server/api/endpoints/users/lists/delete.ts b/packages/backend/src/server/api/endpoints/users/lists/delete.ts
index b7ad96eef0..8cd02ee02a 100644
--- a/packages/backend/src/server/api/endpoints/users/lists/delete.ts
+++ b/packages/backend/src/server/api/endpoints/users/lists/delete.ts
@@ -9,6 +9,8 @@ export const meta = {
 
 	kind: 'write:account',
 
+	description: 'Delete an existing list of users.',
+
 	errors: {
 		noSuchList: {
 			message: 'No such list.',
diff --git a/packages/backend/src/server/api/endpoints/users/lists/list.ts b/packages/backend/src/server/api/endpoints/users/lists/list.ts
index 78311292cb..b337f879b1 100644
--- a/packages/backend/src/server/api/endpoints/users/lists/list.ts
+++ b/packages/backend/src/server/api/endpoints/users/lists/list.ts
@@ -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,
diff --git a/packages/backend/src/server/api/endpoints/users/lists/pull.ts b/packages/backend/src/server/api/endpoints/users/lists/pull.ts
index 76863f07d1..fa7033b02e 100644
--- a/packages/backend/src/server/api/endpoints/users/lists/pull.ts
+++ b/packages/backend/src/server/api/endpoints/users/lists/pull.ts
@@ -11,6 +11,8 @@ export const meta = {
 
 	kind: 'write:account',
 
+	description: 'Remove a user from a list.',
+
 	errors: {
 		noSuchList: {
 			message: 'No such list.',
diff --git a/packages/backend/src/server/api/endpoints/users/lists/push.ts b/packages/backend/src/server/api/endpoints/users/lists/push.ts
index 260665c63a..1db10afc80 100644
--- a/packages/backend/src/server/api/endpoints/users/lists/push.ts
+++ b/packages/backend/src/server/api/endpoints/users/lists/push.ts
@@ -11,6 +11,8 @@ export const meta = {
 
 	kind: 'write:account',
 
+	description: 'Add a user to an existing list.',
+
 	errors: {
 		noSuchList: {
 			message: 'No such list.',
diff --git a/packages/backend/src/server/api/endpoints/users/lists/show.ts b/packages/backend/src/server/api/endpoints/users/lists/show.ts
index 5f51980e95..94d24e1274 100644
--- a/packages/backend/src/server/api/endpoints/users/lists/show.ts
+++ b/packages/backend/src/server/api/endpoints/users/lists/show.ts
@@ -9,6 +9,8 @@ export const meta = {
 
 	kind: 'read:account',
 
+	description: 'Show the properties of a list.',
+
 	res: {
 		type: 'object',
 		optional: false, nullable: false,
diff --git a/packages/backend/src/server/api/endpoints/users/lists/update.ts b/packages/backend/src/server/api/endpoints/users/lists/update.ts
index 52353a14cc..c21cdcf679 100644
--- a/packages/backend/src/server/api/endpoints/users/lists/update.ts
+++ b/packages/backend/src/server/api/endpoints/users/lists/update.ts
@@ -9,6 +9,8 @@ export const meta = {
 
 	kind: 'write:account',
 
+	description: 'Update the properties of a list.',
+
 	res: {
 		type: 'object',
 		optional: false, nullable: false,
diff --git a/packages/backend/src/server/api/endpoints/users/notes.ts b/packages/backend/src/server/api/endpoints/users/notes.ts
index 16318d2225..57dcdfaa88 100644
--- a/packages/backend/src/server/api/endpoints/users/notes.ts
+++ b/packages/backend/src/server/api/endpoints/users/notes.ts
@@ -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,
diff --git a/packages/backend/src/server/api/endpoints/users/pages.ts b/packages/backend/src/server/api/endpoints/users/pages.ts
index b8b3e8192e..85d122c24f 100644
--- a/packages/backend/src/server/api/endpoints/users/pages.ts
+++ b/packages/backend/src/server/api/endpoints/users/pages.ts
@@ -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 = {
diff --git a/packages/backend/src/server/api/endpoints/users/reactions.ts b/packages/backend/src/server/api/endpoints/users/reactions.ts
index c2d1994343..64994aae49 100644
--- a/packages/backend/src/server/api/endpoints/users/reactions.ts
+++ b/packages/backend/src/server/api/endpoints/users/reactions.ts
@@ -9,6 +9,8 @@ export const meta = {
 
 	requireCredential: false,
 
+	description: 'Show all reactions this user made.',
+
 	res: {
 		type: 'array',
 		optional: false, nullable: false,
diff --git a/packages/backend/src/server/api/endpoints/users/recommendation.ts b/packages/backend/src/server/api/endpoints/users/recommendation.ts
index a8f18de522..6fff94ddcf 100644
--- a/packages/backend/src/server/api/endpoints/users/recommendation.ts
+++ b/packages/backend/src/server/api/endpoints/users/recommendation.ts
@@ -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,
diff --git a/packages/backend/src/server/api/endpoints/users/relation.ts b/packages/backend/src/server/api/endpoints/users/relation.ts
index c6262122d4..87cab5fcf1 100644
--- a/packages/backend/src/server/api/endpoints/users/relation.ts
+++ b/packages/backend/src/server/api/endpoints/users/relation.ts
@@ -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: [
diff --git a/packages/backend/src/server/api/endpoints/users/report-abuse.ts b/packages/backend/src/server/api/endpoints/users/report-abuse.ts
index 0be385dbbf..c7c7a3f591 100644
--- a/packages/backend/src/server/api/endpoints/users/report-abuse.ts
+++ b/packages/backend/src/server/api/endpoints/users/report-abuse.ts
@@ -13,6 +13,8 @@ export const meta = {
 
 	requireCredential: true,
 
+	description: 'File a report.',
+
 	errors: {
 		noSuchUser: {
 			message: 'No such user.',
diff --git a/packages/backend/src/server/api/endpoints/users/search-by-username-and-host.ts b/packages/backend/src/server/api/endpoints/users/search-by-username-and-host.ts
index f74d80e2ae..6cbf12b3b5 100644
--- a/packages/backend/src/server/api/endpoints/users/search-by-username-and-host.ts
+++ b/packages/backend/src/server/api/endpoints/users/search-by-username-and-host.ts
@@ -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,
diff --git a/packages/backend/src/server/api/endpoints/users/search.ts b/packages/backend/src/server/api/endpoints/users/search.ts
index f93d4f718b..19c1a2c690 100644
--- a/packages/backend/src/server/api/endpoints/users/search.ts
+++ b/packages/backend/src/server/api/endpoints/users/search.ts
@@ -8,6 +8,8 @@ export const meta = {
 
 	requireCredential: false,
 
+	description: 'Search for users.',
+
 	res: {
 		type: 'array',
 		optional: false, nullable: false,
diff --git a/packages/backend/src/server/api/endpoints/users/show.ts b/packages/backend/src/server/api/endpoints/users/show.ts
index 183ff1b8bb..b31ca30647 100644
--- a/packages/backend/src/server/api/endpoints/users/show.ts
+++ b/packages/backend/src/server/api/endpoints/users/show.ts
@@ -11,6 +11,8 @@ export const meta = {
 
 	requireCredential: false,
 
+	description: 'Show the properties of a user.',
+
 	res: {
 		optional: false, nullable: false,
 		oneOf: [
diff --git a/packages/backend/src/server/api/endpoints/users/stats.ts b/packages/backend/src/server/api/endpoints/users/stats.ts
index 59283e4f2a..d17e8b64b5 100644
--- a/packages/backend/src/server/api/endpoints/users/stats.ts
+++ b/packages/backend/src/server/api/endpoints/users/stats.ts
@@ -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 = {