APIドキュメントの改善 (#6757)

* Update api document in admin/announcements

* Update api document in announcements

* Update api document in i/read-announcements

* Update api document in username/available

* Update api document & Fix typo in API 403 error

* Update api document

* Update api document

* Update api document

* Fix API permission definition

* Update api document

* Update api document

* Update api document

* Update api document

* Update api document

* Update api document

* Update api document

* Update api document

* Fix bug in users (api)

* Apply reviews #6757

* Apply reviews #6757

Co-authored-by: syuilo <Syuilotan@yahoo.co.jp>

src/server/api/endpoints/admin/abuse-user-reports.ts

@@ -5,6 +5,11 @@ import { AbuseUserReports } from '../../../../models';
 import { makePaginationQuery } from '../../common/make-pagination-query';
 
 export const meta = {
+	desc: {
+		'ja-JP': '通報一覧を表示します。',
+		'en-US': 'Show list of abuse user reports.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: true as const,
@@ -46,6 +51,74 @@ export const meta = {
 			]),
 			default: 'combined'
 		},
+	},
+
+	res: {
+		type: 'array' as const,
+		optional: false as const, nullable: false as const,
+		items: {
+			type: 'object' as const,
+			optional: false as const, nullable: false as const,
+			properties: {
+				id: {
+					type: 'string' as const,
+					nullable: false as const, optional: false as const,
+					format: 'id',
+					description: 'The unique identifier for this User.',
+					example: 'xxxxxxxxxx',
+				},
+				createdAt: {
+					type: 'string' as const,
+					nullable: false as const, optional: false as const,
+					format: 'date-time',
+					description: 'The date that the abuse user report was created on Misskey.'
+				},
+				comment: {
+					type: 'string' as const,
+					nullable: false as const, optional: false as const,
+					description: 'The content of the report.',
+				},
+				resolved: {
+					type: 'boolean' as const,
+					nullable: false as const, optional: false as const,
+					description: 'Returns whether this report has been resolved',
+					example: false
+				},
+				reporterId: {
+					type: 'string' as const,
+					nullable: false as const, optional: false as const,
+					format: 'id',
+					description: 'Reporter\'s user ID.'
+				},
+				targetUserId: {
+					type: 'string' as const,
+					nullable: false as const, optional: false as const,
+					format: 'id',
+					description: 'User ID of the person to be reported.'
+				},
+				assigneeId: {
+					type: 'string' as const,
+					nullable: true as const, optional: false as const,
+					format: 'id',
+					description: 'User ID of the person who responded to the report.'
+				},
+				reporter: {
+					type: 'object' as const,
+					nullable: false as const, optional: false as const,
+					ref: 'User'
+				},
+				targetUser: {
+					type: 'object' as const,
+					nullable: false as const, optional: false as const,
+					ref: 'User'
+				},
+				assignee: {
+					type: 'object' as const,
+					nullable: true as const, optional: true as const,
+					ref: 'User'
+				}
+			}
+		}
 	}
 };
 

src/server/api/endpoints/admin/accounts/create.ts

@@ -3,6 +3,11 @@ import { Users } from '../../../../../models';
 import { signup } from '../../../common/signup';
 
 export const meta = {
+	desc: {
+		'ja-JP': 'アカウントを作成します。',
+		'en-US': 'Create a account.'
+	},
+
 	tags: ['admin'],
 
 	params: {
@@ -13,6 +18,19 @@ export const meta = {
 		password: {
 			validator: Users.validatePassword,
 		}
+	},
+
+	res: {
+		type: 'object' as const,
+		optional: false as const, nullable: false as const,
+		ref: 'User',
+		properties: {
+			token: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const,
+				description: 'Token to access this user.'
+			}
+		}
 	}
 };
 

src/server/api/endpoints/admin/announcements/create.ts

@@ -4,6 +4,11 @@ import { Announcements } from '../../../../../models';
 import { genId } from '../../../../../misc/gen-id';
 
 export const meta = {
+	desc: {
+		'ja-JP': 'アナウンスを作成します。',
+		'en-US': 'Create a announcement.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: true as const,
@@ -19,6 +24,47 @@ export const meta = {
 		imageUrl: {
 			validator: $.nullable.str.min(1)
 		}
+	},
+
+	res: {
+		type: 'object' as const,
+		optional: false as const, nullable: false as const,
+		properties: {
+			id: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const,
+				format: 'id',
+				description: 'The unique identifier for this Announcement.',
+				example: 'xxxxxxxxxx',
+			},
+			createdAt: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const,
+				format: 'date-time',
+				description: 'The date that the Announcement was created.'
+			},
+			updatedAt: {
+				type: 'string' as const,
+				optional: false as const, nullable: true as const,
+				format: 'date-time',
+				description: 'The date that the Announcement was updated.'
+			},
+			title: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const,
+				description: 'Announcement title.'
+			},
+			text: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const,
+				description: 'Announcement text.'
+			},
+			imageUrl: {
+				type: 'string' as const,
+				optional: false as const, nullable: true as const,
+				description: 'Announcement image.'
+			}
+		}
 	}
 };
 

src/server/api/endpoints/admin/announcements/delete.ts

@@ -10,6 +10,11 @@ export const meta = {
 	requireCredential: true as const,
 	requireModerator: true,
 
+	desc: {
+		'ja-JP': 'アナウンスを削除します。',
+		'en-US': 'Delete a announcement.'
+	},
+
 	params: {
 		id: {
 			validator: $.type(ID)

src/server/api/endpoints/admin/announcements/list.ts

@@ -5,6 +5,11 @@ import { Announcements, AnnouncementReads } from '../../../../../models';
 import { makePaginationQuery } from '../../../common/make-pagination-query';
 
 export const meta = {
+	desc: {
+		'ja-JP': 'アナウンスのリストを表示します。',
+		'en-US': 'List announcements.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: true as const,
@@ -23,6 +28,56 @@ export const meta = {
 		untilId: {
 			validator: $.optional.type(ID),
 		},
+	},
+
+	res: {
+		type: 'array' as const,
+		optional: false as const, nullable: false as const,
+		items: {
+			type: 'object' as const,
+			optional: false as const, nullable: false as const,
+			properties: {
+				id: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					format: 'id',
+					description: 'The unique identifier for this Announcement.',
+					example: 'xxxxxxxxxx',
+				},
+				createdAt: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					format: 'date-time',
+					description: 'The date that the Announcement was created.'
+				},
+				updatedAt: {
+					type: 'string' as const,
+					optional: false as const, nullable: true as const,
+					format: 'date-time',
+					description: 'The date that the Announcement was updated.'
+				},
+				text: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					description: 'Announcement text.'
+				},
+				title: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					description: 'Announcement title.'
+				},
+				imageUrl: {
+					type: 'string' as const,
+					optional: false as const, nullable: true as const,
+					description: 'Announcement image.'
+				},
+				reads: {
+					type: 'number' as const,
+					optional: false as const, nullable: false as const,
+					description: 'Number of people who read this announcement.'
+				}
+			}
+		}
 	}
 };
 

src/server/api/endpoints/admin/announcements/update.ts

@@ -5,6 +5,11 @@ import { Announcements } from '../../../../../models';
 import { ApiError } from '../../../error';
 
 export const meta = {
+	desc: {
+		'ja-JP': 'アナウンスの内容を変更します。',
+		'en-US': 'Update a annoucement.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: true as const,

src/server/api/endpoints/admin/delete-all-files-of-a-user.ts

@@ -5,6 +5,11 @@ import { DriveFiles } from '../../../../models';
 import { ID } from '../../../../misc/cafy-id';
 
 export const meta = {
+	desc: {
+		'ja-JP': '対象のユーザーのファイルを全て削除します。',
+		'en-US': 'Delete all files to specified user.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: true as const,

src/server/api/endpoints/admin/delete-logs.ts

@@ -2,6 +2,11 @@ import define from '../../define';
 import { Logs } from '../../../../models';
 
 export const meta = {
+	desc: {
+		'ja-JP': 'ログを全て削除します。',
+		'en-US': 'Delete all logs.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: true as const,

src/server/api/endpoints/admin/drive/clean-remote-files.ts

@@ -2,6 +2,11 @@ import define from '../../../define';
 import { createCleanRemoteFilesJob } from '../../../../../queue';
 
 export const meta = {
+	desc: {
+		'ja-JP': 'キャッシュされたリモートファイルをすべて削除します。',
+		'en-US': 'Deletes all cached remote files.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: true as const,

src/server/api/endpoints/admin/drive/cleanup.ts

@@ -4,6 +4,11 @@ import { deleteFile } from '../../../../../services/drive/delete-file';
 import { DriveFiles } from '../../../../../models';
 
 export const meta = {
+	desc: {
+		'ja-JP': '使用されていないユーザーのファイルを削除します。',
+		'en-US': 'Delete the unused user\'s files.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: true as const,

src/server/api/endpoints/admin/drive/files.ts

@@ -5,6 +5,11 @@ import { makePaginationQuery } from '../../../common/make-pagination-query';
 import { ID } from '../../../../../misc/cafy-id';
 
 export const meta = {
+	desc: {
+		'ja-JP': '管理用のドライブの一覧を表示します。',
+		'en-US': 'Displays a list of management drives.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: false as const,
@@ -41,6 +46,16 @@ export const meta = {
 			validator: $.optional.nullable.str,
 			default: null
 		},
+	},
+
+	res: {
+		type: 'array' as const,
+		optional: false as const, nullable: false as const,
+		items: {
+			type: 'object' as const,
+			optional: false as const, nullable: false as const,
+			ref: 'DriveFile'
+		}
 	}
 };
 

src/server/api/endpoints/admin/drive/show-file.ts

@@ -26,6 +26,154 @@ export const meta = {
 			code: 'NO_SUCH_FILE',
 			id: 'caf3ca38-c6e5-472e-a30c-b05377dcc240'
 		}
+	},
+
+	res: {
+		type: 'object' as const,
+		optional: false as const, nullable: false as const,
+		properties: {
+			id: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const,
+				format: 'id',
+				description: 'The unique identifier for this Drive file.',
+				example: 'xxxxxxxxxx',
+			},
+			createdAt: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const,
+				format: 'date-time',
+				description: 'The date that the Drive file was created on Misskey.'
+			},
+			userId: {
+				type: 'string' as const,
+				optional: false as const, nullable: true as const,
+				format: 'id',
+				description: 'Owner ID of this Drive file.',
+				example: 'xxxxxxxxxx',
+			},
+			userHost: {
+				type: 'string' as const,
+				optional: false as const, nullable: true as const
+			},
+			md5: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const,
+				format: 'md5',
+				description: 'The MD5 hash of this Drive file.',
+				example: '15eca7fba0480996e2245f5185bf39f2'
+			},
+			name: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const,
+				description: 'The file name with extension.',
+				example: 'lenna.jpg'
+			},
+			type: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const,
+				description: 'The MIME type of this Drive file.',
+				example: 'image/jpeg'
+			},
+			size: {
+				type: 'number' as const,
+				optional: false as const, nullable: false as const,
+				description: 'The size of this Drive file. (bytes)',
+				example: 51469
+			},
+			comment: {
+				type: 'string' as const,
+				optional: false as const, nullable: true as const
+			},
+			blurhash: {
+				type: 'string' as const,
+				optional: false as const, nullable: true as const
+			},
+			properties: {
+				type: 'object' as const,
+				optional: false as const, nullable: false as const,
+				properties: {
+					width: {
+						type: 'number' as const,
+						optional: false as const, nullable: false as const,
+						example: 1280
+					},
+					height: {
+						type: 'number' as const,
+						optional: false as const, nullable: false as const,
+						example: 720
+					},
+					avgColor: {
+						type: 'string' as const,
+						optional: true as const, nullable: false as const,
+						example: 'rgb(40,65,87)'
+					}
+				}
+			},
+			storedInternal: {
+				type: 'boolean' as const,
+				optional: false as const, nullable: true as const,
+				description: 'Indicates whether this file is stored in the same location as Misskey itself',
+				example: true
+			},
+			url: {
+				type: 'string' as const,
+				optional: false as const, nullable: true as const,
+				format: 'url',
+				description: 'The URL of this Drive file.',
+			},
+			thumbnailUrl: {
+				type: 'string' as const,
+				optional: false as const, nullable: true as const,
+				format: 'url',
+				description: 'The thumbnail URL of this Drive file.',
+			},
+			webpublicUrl: {
+				type: 'string' as const,
+				optional: false as const, nullable: true as const,
+				format: 'url',
+				description: 'The public URL of this Drive file.',
+			},
+			accessKey: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const,
+				description: 'Access key to access this file'
+			},
+			thumbnailAccessKey: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const,
+				description: 'Access key to access this file for thumbnail'
+			},
+			webpublicAccessKey: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const,
+				description: 'Access key to access this file for webpublic'
+			},
+			uri: {
+				type: 'string' as const,
+				optional: false as const, nullable: true as const
+			},
+			src: {
+				type: 'string' as const,
+				optional: false as const, nullable: true as const
+			},
+			folderId: {
+				type: 'string' as const,
+				optional: false as const, nullable: true as const,
+				format: 'id',
+				description: 'The parent folder ID of this Drive file.',
+				example: 'xxxxxxxxxx',
+			},
+			isSensitive: {
+				type: 'boolean' as const,
+				optional: false as const, nullable: false as const,
+				description: 'Whether this Drive file is sensitive.',
+			},
+			isLink: {
+				type: 'boolean' as const,
+				optional: false as const, nullable: false as const
+			}
+		}
 	}
 };
 

src/server/api/endpoints/admin/emoji/copy.ts

@@ -9,6 +9,11 @@ import { ID } from '../../../../../misc/cafy-id';
 import uploadFromUrl from '../../../../../services/drive/upload-from-url';
 
 export const meta = {
+	desc: {
+		'ja-JP': '選択したカスタム絵文字をコピーします。',
+		'en-US': 'Copies the selected custom emoji.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: true as const,
@@ -26,6 +31,19 @@ export const meta = {
 			code: 'NO_SUCH_EMOJI',
 			id: 'e2785b66-dca3-4087-9cac-b93c541cc425'
 		}
+	},
+
+	res: {
+		type: 'object' as const,
+		optional: false as const, nullable: false as const,
+		properties: {
+			id: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const,
+				format: 'id',
+				description: 'New copied emoji ID'
+			}
+		}
 	}
 };
 

src/server/api/endpoints/admin/emoji/list-remote.ts

@@ -7,7 +7,8 @@ import { ID } from '../../../../../misc/cafy-id';
 
 export const meta = {
 	desc: {
-		'ja-JP': 'カスタム絵文字を取得します。'
+		'ja-JP': 'リモートのカスタム絵文字一覧を取得します。',
+		'en-US': 'Gets a list of remote custom emojis.'
 	},
 
 	tags: ['admin'],
@@ -38,6 +39,52 @@ export const meta = {
 		untilId: {
 			validator: $.optional.type(ID),
 		}
+	},
+
+	res: {
+		type: 'array' as const,
+		optional: false as const, nullable: false as const,
+		items: {
+			type: 'object' as const,
+			optional: false as const, nullable: false as const,
+			properties: {
+				id: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					format: 'id',
+					description: 'The unique identifier for this Emoji.'
+				},
+				aliases: {
+					type: 'array' as const,
+					optional: false as const, nullable: false as const,
+					description: 'List to make it easier to be displayed as a candidate when entering emoji.',
+					items: {
+						type: 'string' as const,
+						optional: false as const, nullable: false as const
+					}
+				},
+				name: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					description: 'Official name of custom emoji.'
+				},
+				category: {
+					type: 'string' as const,
+					optional: false as const, nullable: true as const,
+					description: 'Names categorized in the emoji list.'
+				},
+				host: {
+					type: 'string' as const,
+					optional: false as const, nullable: true as const,
+					description: 'If it is another server, the FQDN will be returned here.'
+				},
+				url: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					description: 'Image URL of emoji.'
+				}
+			}
+		}
 	}
 };
 

src/server/api/endpoints/admin/emoji/list.ts

@@ -7,7 +7,8 @@ import { Emoji } from '../../../../../models/entities/emoji';
 
 export const meta = {
 	desc: {
-		'ja-JP': 'カスタム絵文字を取得します。'
+		'ja-JP': 'カスタム絵文字一覧を取得します。',
+		'en-US': 'List custom emojis.'
 	},
 
 	tags: ['admin'],
@@ -33,6 +34,52 @@ export const meta = {
 		untilId: {
 			validator: $.optional.type(ID),
 		}
+	},
+
+	res: {
+		type: 'array' as const,
+		optional: false as const, nullable: false as const,
+		items: {
+			type: 'object' as const,
+			optional: false as const, nullable: false as const,
+			properties: {
+				id: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					format: 'id',
+					description: 'The unique identifier for this Emoji.'
+				},
+				aliases: {
+					type: 'array' as const,
+					optional: false as const, nullable: false as const,
+					description: 'List to make it easier to be displayed as a candidate when entering emoji.',
+					items: {
+						type: 'string' as const,
+						optional: false as const, nullable: false as const
+					}
+				},
+				name: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					description: 'Official name of custom emoji.'
+				},
+				category: {
+					type: 'string' as const,
+					optional: false as const, nullable: true as const,
+					description: 'Names categorized in the emoji list.'
+				},
+				host: {
+					type: 'string' as const,
+					optional: false as const, nullable: true as const,
+					description: 'If it is another server, the FQDN will be returned here.'
+				},
+				url: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					description: 'Image URL of emoji.'
+				}
+			}
+		}
 	}
 };
 

src/server/api/endpoints/admin/federation/delete-all-files.ts

@@ -4,6 +4,11 @@ import { deleteFile } from '../../../../../services/drive/delete-file';
 import { DriveFiles } from '../../../../../models';
 
 export const meta = {
+	desc: {
+		'ja-JP': '指定したドメインのファイルを全て削除します。',
+		'en-US': 'Deletes all files in the specified domain.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: true as const,

src/server/api/endpoints/admin/federation/remove-all-following.ts

@@ -4,6 +4,11 @@ import deleteFollowing from '../../../../../services/following/delete';
 import { Followings, Users } from '../../../../../models';
 
 export const meta = {
+	desc: {
+		'ja-JP': '指定したドメインの全ユーザーのフォローを全て解除します。',
+		'en-US': 'Unfollow all users in the specified domain.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: true as const,

src/server/api/endpoints/admin/federation/update-instance.ts

@@ -4,6 +4,11 @@ import { Instances } from '../../../../../models';
 import { toPuny } from '../../../../../misc/convert-host';
 
 export const meta = {
+	desc: {
+		'ja-JP': '指定したドメインのアクティビティの配信を停止するかを選択します。',
+		'en-US': 'Select whether to undeliver the activity for the specified domain.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: true as const,

src/server/api/endpoints/admin/get-table-stats.ts

@@ -6,6 +6,7 @@ export const meta = {
 	requireModerator: true,
 
 	desc: {
+		'ja-JP': 'テーブル情報を取得します。',
 		'en-US': 'Get table stats'
 	},
 
@@ -13,6 +14,17 @@ export const meta = {
 
 	params: {
 	},
+
+	res: {
+		type: 'object' as const,
+		optional: false as const, nullable: false as const,
+		example: {
+			migrations: {
+				count: 66,
+				size: 32768
+			},
+		}
+	}
 };
 
 export default define(meta, async () => {

src/server/api/endpoints/admin/invite.ts

@@ -5,7 +5,8 @@ import { genId } from '../../../../misc/gen-id';
 
 export const meta = {
 	desc: {
-		'ja-JP': '招待コードを発行します。'
+		'ja-JP': '招待コードを発行します。',
+		'en-US': 'Issue an invitation code.'
 	},
 
 	tags: ['admin'],
@@ -13,7 +14,22 @@ export const meta = {
 	requireCredential: true as const,
 	requireModerator: true,
 
-	params: {}
+	params: {},
+
+	res: {
+		type: 'object' as const,
+		optional: false as const, nullable: false as const,
+		properties: {
+			code: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const,
+				description: 'Give this code to the applicant for registration.',
+				example: '2ERUA5VR',
+				maxLength: 8,
+				minLength: 8
+			}
+		}
+	}
 };
 
 export default define(meta, async () => {

src/server/api/endpoints/admin/logs.ts

@@ -4,6 +4,11 @@ import { Logs } from '../../../../models';
 import { Brackets } from 'typeorm';
 
 export const meta = {
+	desc: {
+		'ja-JP': 'ログを表示します。',
+		'en-US': 'Show logs.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: true as const,
@@ -24,6 +29,60 @@ export const meta = {
 			validator: $.optional.nullable.str,
 			default: null as any
 		}
+	},
+
+	res: {
+		type: 'array' as const,
+		optional: false as const, nullable: false as const,
+		items: {
+			type: 'object' as const,
+			optional: false as const, nullable: false as const,
+			properties: {
+				id: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					format: 'id',
+					description: 'The unique identifier for this log.',
+					example: 'xxxxxxxxxx',
+				},
+				createdAt: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					format: 'date-time',
+					description: 'The date that the Drive file was created on Misskey.'
+				},
+				domain: {
+					type: 'array' as const,
+					optional: false as const, nullable: false as const,
+					items: {
+						type: 'string' as const,
+						optional: true as const, nullable: false as const
+					}
+				},
+				level: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const
+				},
+				worker: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const
+				},
+				machine: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					description: 'The name of the running machine.'
+				},
+				message: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					description: 'Log body.'
+				},
+				data: {
+					type: 'object' as const,
+					optional: false as const, nullable: false as const
+				}
+			}
+		}
 	}
 };
 

src/server/api/endpoints/admin/promo/create.ts

@@ -6,6 +6,11 @@ import { getNote } from '../../../common/getters';
 import { PromoNotes } from '../../../../../models';
 
 export const meta = {
+	desc: {
+		'ja-JP': 'プロモーションを作成します。',
+		'en-US': 'Create a promotion.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: true as const,

src/server/api/endpoints/admin/queue/clear.ts

@@ -3,6 +3,11 @@ import { destroy } from '../../../../../queue';
 import { insertModerationLog } from '../../../../../services/insert-moderation-log';
 
 export const meta = {
+	desc: {
+		'ja-JP': 'ジョブキューを全て削除します。',
+		'en-US': 'Delete all job queues.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: true as const,

src/server/api/endpoints/admin/queue/deliver-delayed.ts

@@ -2,12 +2,42 @@ import define from '../../../define';
 import { deliverQueue } from '../../../../../queue';
 
 export const meta = {
+	desc: {
+		'ja-JP': '他サーバーへ送るキューの遅延一覧を返します。',
+		'en-US': 'Returns a list of delays in queues sent to other servers.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: true as const,
 	requireModerator: true,
 
 	params: {
+	},
+
+	res: {
+		type: 'array' as const,
+		optional: false as const, nullable: false as const,
+		items: {
+			type: 'array' as const,
+			optional: false as const, nullable: false as const,
+			items: {
+				anyOf: [
+					{
+						type: 'string' as const,
+						description: 'FQDN to fediverse server'
+					},
+					{
+						type: 'number' as const,
+						description: 'Delayed queue counts'
+					}
+				]
+			}
+		},
+		example: [[
+			'example.com',
+			12
+		]]
 	}
 };
 

src/server/api/endpoints/admin/queue/inbox-delayed.ts

@@ -2,12 +2,42 @@ import define from '../../../define';
 import { inboxQueue } from '../../../../../queue';
 
 export const meta = {
+	desc: {
+		'ja-JP': 'このサーバーへのキューの遅延一覧を返します。',
+		'en-US': 'Returns a list of queue delays to this server.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: true as const,
 	requireModerator: true,
 
 	params: {
+	},
+
+	res: {
+		type: 'array' as const,
+		optional: false as const, nullable: false as const,
+		items: {
+			type: 'array' as const,
+			optional: false as const, nullable: false as const,
+			items: {
+				anyOf: [
+					{
+						type: 'string' as const,
+						description: 'FQDN to fediverse server'
+					},
+					{
+						type: 'number' as const,
+						description: 'Delayed queue counts'
+					}
+				]
+			}
+		},
+		example: [[
+			'example.com',
+			12
+		]]
 	}
 };
 

src/server/api/endpoints/admin/queue/jobs.ts

@@ -3,6 +3,11 @@ import define from '../../../define';
 import { deliverQueue, inboxQueue, dbQueue, objectStorageQueue } from '../../../../../queue';
 
 export const meta = {
+	desc: {
+		'ja-JP': 'ジョブ一覧を表示します。',
+		'en-US': 'Display the job list.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: true as const,
@@ -21,6 +26,38 @@ export const meta = {
 			validator: $.optional.num,
 			default: 50
 		},
+	},
+
+	res: {
+		type: 'array' as const,
+		optional: false as const, nullable: false as const,
+		items: {
+			type: 'object' as const,
+			optional: false as const, nullable: false as const,
+			properties: {
+				id: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					format: 'id'
+				},
+				data: {
+					type: 'object' as const,
+					optional: false as const, nullable: false as const
+				},
+				attempts: {
+					type: 'number' as const,
+					optional: false as const, nullable: false as const
+				},
+				maxAttempts: {
+					type: 'number' as const,
+					optional: false as const, nullable: false as const
+				},
+				timestamp: {
+					type: 'number' as const,
+					optional: false as const, nullable: false as const
+				}
+			}
+		}
 	}
 };
 

src/server/api/endpoints/admin/queue/stats.ts

@@ -2,12 +2,36 @@ import define from '../../../define';
 import { deliverQueue, inboxQueue, dbQueue, objectStorageQueue } from '../../../../../queue';
 
 export const meta = {
+	desc: {
+		'ja-JP': 'キューの状態を返します。',
+		'en-US': 'Returns the status of the queue.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: true as const,
 	requireModerator: true,
 
-	params: {}
+	params: {},
+
+	res: {
+		type: 'object' as const,
+		optional: false as const, nullable: false as const,
+		properties: {
+			deliver: {
+				ref: 'QueueCount'
+			},
+			inbox: {
+				ref: 'QueueCount'
+			},
+			db: {
+				ref: 'QueueCount'
+			},
+			objectStorage: {
+				ref: 'QueueCount'
+			}
+		}
+	}
 };
 
 export default define(meta, async (ps) => {

src/server/api/endpoints/admin/relays/add.ts

@@ -5,7 +5,8 @@ import { ApiError } from '../../../error';
 
 export const meta = {
 	desc: {
-		'ja-JP': 'Add relay'
+		'ja-JP': 'リレーを追加します。',
+		'en-US': 'Add relay'
 	},
 
 	tags: ['admin'],
@@ -25,6 +26,33 @@ export const meta = {
 			code: 'INVALID_URL',
 			id: 'fb8c92d3-d4e5-44e7-b3d4-800d5cef8b2c'
 		},
+	},
+
+	res: {
+		type: 'object' as const,
+		optional: false as const, nullable: false as const,
+		properties: {
+			id: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const,
+				format: 'id'
+			},
+			inbox: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const,
+				format: 'url'
+			},
+			status: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const,
+				default: 'requesting',
+				enum: [
+					'requesting',
+					'accepted',
+					'rejected'
+				]
+			}
+		}
 	}
 };
 

src/server/api/endpoints/admin/relays/list.ts

@@ -3,7 +3,8 @@ import { listRelay } from '../../../../../services/relay';
 
 export const meta = {
 	desc: {
-		'ja-JP': 'List relay'
+		'ja-JP': 'リレー一覧を表示します。',
+		'en-US': 'List relay'
 	},
 
 	tags: ['admin'],
@@ -13,6 +14,37 @@ export const meta = {
 
 	params: {
 	},
+
+	res: {
+		type: 'array' as const,
+		optional: false as const, nullable: false as const,
+		items: {
+			type: 'object' as const,
+			optional: false as const, nullable: false as const,
+			properties: {
+				id: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					format: 'id'
+				},
+				inbox: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					format: 'url'
+				},
+				status: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					default: 'requesting',
+					enum: [
+						'requesting',
+						'accepted',
+						'rejected'
+					]
+				}
+			}
+		}
+	}
 };
 
 export default define(meta, async (ps, user) => {

src/server/api/endpoints/admin/relays/remove.ts

@@ -4,7 +4,8 @@ import { removeRelay } from '../../../../../services/relay';
 
 export const meta = {
 	desc: {
-		'ja-JP': 'Remove relay'
+		'ja-JP': 'リレーを削除します。',
+		'en-US': 'Remove relay'
 	},
 
 	tags: ['admin'],

src/server/api/endpoints/admin/reset-password.ts

@@ -8,6 +8,7 @@ import { Users, UserProfiles } from '../../../../models';
 export const meta = {
 	desc: {
 		'ja-JP': '指定したユーザーのパスワードをリセットします。',
+		'en-US': 'Reset password to specified user.'
 	},
 
 	tags: ['admin'],
@@ -23,6 +24,19 @@ export const meta = {
 				'en-US': 'The user ID which you want to suspend'
 			}
 		},
+	},
+
+	res: {
+		type: 'object' as const,
+		optional: false as const, nullable: false as const,
+		properties: {
+			password: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const,
+				minLength: 8,
+				maxLength: 8
+			}
+		}
 	}
 };
 

src/server/api/endpoints/admin/resolve-abuse-user-report.ts

@@ -4,6 +4,11 @@ import define from '../../define';
 import { AbuseUserReports } from '../../../../models';
 
 export const meta = {
+	desc: {
+		'ja-JP': '指定した通報を解決済みにします。',
+		'en-US': 'Marks the specified report as resolved.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: true as const,

src/server/api/endpoints/admin/resync-chart.ts

@@ -3,6 +3,11 @@ import { driveChart, notesChart, usersChart, instanceChart } from '../../../../s
 import { insertModerationLog } from '../../../../services/insert-moderation-log';
 
 export const meta = {
+	desc: {
+		'ja-JP': 'チャートを再同期します。',
+		'en-US': 'Resync the chart.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: true as const,

src/server/api/endpoints/admin/send-email.ts

@@ -3,6 +3,11 @@ import define from '../../define';
 import { sendEmail } from '../../../../services/send-email';
 
 export const meta = {
+	desc: {
+		'ja-JP': 'メールを送信します。',
+		'en-US': 'Send a mail.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: true as const,

src/server/api/endpoints/admin/server-info.ts

@@ -9,12 +9,100 @@ export const meta = {
 	requireModerator: true,
 
 	desc: {
+		'ja-JP': 'サーバー情報を表示します。',
+		'en-US': 'Show server information.'
 	},
 
 	tags: ['admin', 'meta'],
 
 	params: {
 	},
+
+	res: {
+		type: 'object' as const,
+		optional: false as const, nullable: false as const,
+		properties: {
+			machine: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const,
+				description: 'The name of the running server'
+			},
+			os: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const,
+				description: 'OS used by the server',
+				example: 'linux'
+			},
+			node: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const,
+				description: 'Version of Node.js'
+			},
+			psql: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const,
+				description: 'Version of Postgresql'
+			},
+			cpu: {
+				type: 'object' as const,
+				optional: false as const, nullable: false as const,
+				properties: {
+					model: {
+						type: 'string' as const,
+						optional: false as const, nullable: false as const,
+						description: 'The name of the CPU you are using'
+					},
+					cores: {
+						type: 'number' as const,
+						optional: false as const, nullable: false as const,
+						description: 'Number of CPU cores used (number of logical processors)'
+					}
+				}
+			},
+			mem: {
+				type: 'object' as const,
+				optional: false as const, nullable: false as const,
+				properties: {
+					total: {
+						type: 'number' as const,
+						optional: false as const, nullable: false as const,
+						format: 'bytes',
+						description: 'RAM capacity.'
+					}
+				}
+			},
+			fs: {
+				type: 'object' as const,
+				optional: false as const, nullable: false as const,
+				properties: {
+					total: {
+						type: 'number' as const,
+						optional: false as const, nullable: false as const,
+						format: 'bytes',
+						description: 'Total storage capacity.'
+					},
+					used: {
+						type: 'number' as const,
+						optional: false as const, nullable: false as const,
+						format: 'bytes',
+						description: 'Amount of storage used'
+					}
+				}
+			},
+			net: {
+				type: 'object' as const,
+				optional: false as const, nullable: false as const,
+				properties: {
+					interface: {
+						type: 'string' as const,
+						optional: false as const, nullable: false as const,
+						description: 'The interface name of your network.',
+						example: 'eth0'
+					}
+				}
+			}
+		}
+	}
 };
 
 export default define(meta, async () => {

src/server/api/endpoints/admin/show-moderation-logs.ts

@@ -5,6 +5,11 @@ import { ModerationLogs } from '../../../../models';
 import { makePaginationQuery } from '../../common/make-pagination-query';
 
 export const meta = {
+	desc: {
+		'ja-JP': 'モデレーションログ一覧を表示します。',
+		'en-US': 'Display the moderation log list.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: true as const,
@@ -23,6 +28,45 @@ export const meta = {
 		untilId: {
 			validator: $.optional.type(ID),
 		},
+	},
+
+	res: {
+		type: 'array' as const,
+		optional: false as const, nullable: false as const,
+		items: {
+			type: 'object' as const,
+			optional: false as const, nullable: false as const,
+			properties: {
+				id: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					format: 'id'
+				},
+				createdAt: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					format: 'date-time'
+				},
+				type: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const
+				},
+				info: {
+					type: 'object' as const,
+					optional: false as const, nullable: false as const
+				},
+				userId: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					format: 'id'
+				},
+				user: {
+					type: 'object' as const,
+					optional: false as const, nullable: false as const,
+					ref: 'User'
+				}
+			}
+		}
 	}
 };
 

src/server/api/endpoints/admin/show-user.ts

@@ -5,7 +5,8 @@ import { Users } from '../../../../models';
 
 export const meta = {
 	desc: {
-		'ja-JP': '指定したユーザーの情報を取得します。',
+		'ja-JP': '指定したユーザーの情報を取得します（管理者向け）。',
+		'en-US': 'Gets the information of the specified user (for administrators).'
 	},
 
 	tags: ['admin'],
@@ -21,6 +22,149 @@ export const meta = {
 				'en-US': 'The user ID which you want to suspend'
 			}
 		},
+	},
+
+	res: {
+		type: 'object' as const,
+		nullable: false as const, optional: false as const,
+		properties: {
+			id: {
+				type: 'string' as const,
+				nullable: false as const, optional: false as const,
+				format: 'id'
+			},
+			createdAt: {
+				type: 'string' as const,
+				nullable: false as const, optional: false as const,
+				format: 'date-time'
+			},
+			updatedAt: {
+				type: 'string' as const,
+				nullable: true as const, optional: false as const,
+				format: 'date-time'
+			},
+			lastFetchedAt: {
+				type: 'string' as const,
+				nullable: true as const, optional: false as const
+			},
+			username: {
+				type: 'string' as const,
+				nullable: false as const, optional: false as const
+			},
+			name: {
+				type: 'string' as const,
+				nullable: false as const, optional: false as const
+			},
+			folowersCount: {
+				type: 'number' as const,
+				nullable: false as const, optional: false as const
+			},
+			followingCount: {
+				type: 'number' as const,
+				nullable: false as const, optional: false as const
+			},
+			notesCount: {
+				type: 'number' as const,
+				nullable: false as const, optional: false as const
+			},
+			avatarId: {
+				type: 'string' as const,
+				nullable: true as const, optional: false as const
+			},
+			bannerId: {
+				type: 'string' as const,
+				nullable: true as const, optional: false as const
+			},
+			tags: {
+				type: 'array' as const,
+				nullable: false as const, optional: false as const,
+				items: {
+					type: 'string' as const,
+					nullable: false as const, optional: false as const
+				}
+			},
+			avatarUrl: {
+				type: 'string' as const,
+				nullable: true as const, optional: false as const,
+				format: 'url'
+			},
+			bannerUrl: {
+				type: 'string' as const,
+				nullable: true as const, optional: false as const,
+				format: 'url'
+			},
+			avatarBlurhash: {
+				type: 'any' as const,
+				nullable: true as const, optional: false as const,
+				default: null
+			},
+			bannerBlurhash: {
+				type: 'any' as const,
+				nullable: true as const, optional: false as const,
+				default: null
+			},
+			isSuspended: {
+				type: 'boolean' as const,
+				nullable: false as const, optional: false as const
+			},
+			isSilenced: {
+				type: 'boolean' as const,
+				nullable: false as const, optional: false as const
+			},
+			isLocked: {
+				type: 'boolean' as const,
+				nullable: false as const, optional: false as const,
+			},
+			isBot: {
+				type: 'boolean' as const,
+				nullable: false as const, optional: false as const
+			},
+			isCat: {
+				type: 'boolean' as const,
+				nullable: false as const, optional: false as const
+			},
+			isAdmin: {
+				type: 'boolean' as const,
+				nullable: false as const, optional: false as const
+			},
+			isModerator: {
+				type: 'boolean' as const,
+				nullable: false as const, optional: false as const
+			},
+			emojis: {
+				type: 'array' as const,
+				nullable: false as const, optional: false as const,
+				items: {
+					type: 'string' as const,
+					nullable: false as const, optional: false as const
+				}
+			},
+			host: {
+				type: 'string' as const,
+				nullable: true as const, optional: false as const
+			},
+			inbox: {
+				type: 'string' as const,
+				nullable: true as const, optional: false as const
+			},
+			sharedInbox: {
+				type: 'string' as const,
+				nullable: true as const, optional: false as const
+			},
+			featured: {
+				type: 'string' as const,
+				nullable: true as const, optional: false as const
+			},
+			uri: {
+				type: 'string' as const,
+				nullable: true as const, optional: false as const
+			},
+			token: {
+				type: 'string' as const,
+				nullable: false as const, optional: false as const,
+				default: '<MASKED>'
+			}
+		}
 	}
 };
 

src/server/api/endpoints/admin/show-users.ts

@@ -3,6 +3,11 @@ import define from '../../define';
 import { Users } from '../../../../models';
 
 export const meta = {
+	desc: {
+		'ja-JP': '管理者用のユーザー一覧を表示します。',
+		'en-US': 'Displays a list of users for administrators.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: true as const,
@@ -61,6 +66,16 @@ export const meta = {
 			validator: $.optional.str,
 			default: null
 		}
+	},
+
+	res: {
+		type: 'array' as const,
+		nullable: false as const, optional: false as const,
+		items: {
+			type: 'object' as const,
+			nullable: false as const, optional: false as const,
+			ref: 'User'
+		}
 	}
 };
 

src/server/api/endpoints/admin/vacuum.ts

@@ -4,6 +4,11 @@ import { getConnection } from 'typeorm';
 import { insertModerationLog } from '../../../../services/insert-moderation-log';
 
 export const meta = {
+	desc: {
+		'ja-JP': 'データベースのメンテナンスを行います。',
+		'en-US': 'Perform database maintenance.'
+	},
+
 	tags: ['admin'],
 
 	requireCredential: true as const,