Introduce OpenAPI specs (#4351)

* wip

* wip

* wip

* Update index.ts

* Update gen-openapi-spec.ts

* Update api.ja-JP.md

* Fix

* Improve doc

* Update gen-openapi-spec.ts

* Update redoc.html

* Improve doc

* Update gen-openapi-spec.ts

* Improve doc

* Update CHANGELOG.md

16 files changed, 44 insertions, 1 deletions

diff --git a/src/server/api/endpoints/users/followers.ts b/src/server/api/endpoints/users/followers.ts
index cb5b047626..32c75fc8d4 100644
--- a/src/server/api/endpoints/users/followers.ts
+++ b/src/server/api/endpoints/users/followers.ts
@@ -13,6 +13,8 @@ export const meta = {
 		'en-US': 'Get followers of a user.'
 	},
 
+	tags: ['users'],
+
 	requireCredential: false,
 
 	params: {
diff --git a/src/server/api/endpoints/users/following.ts b/src/server/api/endpoints/users/following.ts
index 04abe5f4b3..3ce103621b 100644
--- a/src/server/api/endpoints/users/following.ts
+++ b/src/server/api/endpoints/users/following.ts
@@ -13,6 +13,8 @@ export const meta = {
 		'en-US': 'Get following users of a user.'
 	},
 
+	tags: ['users'],
+
 	requireCredential: false,
 
 	params: {
diff --git a/src/server/api/endpoints/users/get_frequently_replied_users.ts b/src/server/api/endpoints/users/get_frequently_replied_users.ts
index 0b90e489c2..6f9c746acd 100644
--- a/src/server/api/endpoints/users/get_frequently_replied_users.ts
+++ b/src/server/api/endpoints/users/get_frequently_replied_users.ts
@@ -9,6 +9,8 @@ import { ApiError } from '../../error';
 import { getUser } from '../../common/getters';
 
 export const meta = {
+	tags: ['users'],
+
 	requireCredential: false,
 
 	params: {
diff --git a/src/server/api/endpoints/users/lists/create.ts b/src/server/api/endpoints/users/lists/create.ts
index a3d91b6c25..00d2538c9f 100644
--- a/src/server/api/endpoints/users/lists/create.ts
+++ b/src/server/api/endpoints/users/lists/create.ts
@@ -8,6 +8,8 @@ export const meta = {
 		'en-US': 'Create a user list'
 	},
 
+	tags: ['lists'],
+
 	requireCredential: true,
 
 	kind: 'account-write',
diff --git a/src/server/api/endpoints/users/lists/delete.ts b/src/server/api/endpoints/users/lists/delete.ts
index 6aaf4701d4..d8faaa928c 100644
--- a/src/server/api/endpoints/users/lists/delete.ts
+++ b/src/server/api/endpoints/users/lists/delete.ts
@@ -10,6 +10,8 @@ export const meta = {
 		'en-US': 'Delete a user list'
 	},
 
+	tags: ['lists'],
+
 	requireCredential: true,
 
 	kind: 'account-write',
diff --git a/src/server/api/endpoints/users/lists/list.ts b/src/server/api/endpoints/users/lists/list.ts
index 5bd662878d..632f4e7e5b 100644
--- a/src/server/api/endpoints/users/lists/list.ts
+++ b/src/server/api/endpoints/users/lists/list.ts
@@ -6,6 +6,8 @@ export const meta = {
 		'ja-JP': '自分の作成したユーザーリスト一覧を取得します。'
 	},
 
+	tags: ['lists', 'account'],
+
 	requireCredential: true,
 
 	kind: 'account-read'
diff --git a/src/server/api/endpoints/users/lists/pull.ts b/src/server/api/endpoints/users/lists/pull.ts
index 7c438ff3d6..0eee1975db 100644
--- a/src/server/api/endpoints/users/lists/pull.ts
+++ b/src/server/api/endpoints/users/lists/pull.ts
@@ -13,6 +13,8 @@ export const meta = {
 		'en-US': 'Remove a user to a user list.'
 	},
 
+	tags: ['lists', 'users'],
+
 	requireCredential: true,
 
 	kind: 'account-write',
diff --git a/src/server/api/endpoints/users/lists/push.ts b/src/server/api/endpoints/users/lists/push.ts
index c63bbb6ac0..6b47f9dc71 100644
--- a/src/server/api/endpoints/users/lists/push.ts
+++ b/src/server/api/endpoints/users/lists/push.ts
@@ -16,6 +16,8 @@ export const meta = {
 		'en-US': 'Add a user to a user list.'
 	},
 
+	tags: ['lists', 'users'],
+
 	requireCredential: true,
 
 	kind: 'account-write',
diff --git a/src/server/api/endpoints/users/lists/show.ts b/src/server/api/endpoints/users/lists/show.ts
index 3bd8ce6573..2f3c8889ad 100644
--- a/src/server/api/endpoints/users/lists/show.ts
+++ b/src/server/api/endpoints/users/lists/show.ts
@@ -10,6 +10,8 @@ export const meta = {
 		'en-US': 'Show a user list.'
 	},
 
+	tags: ['lists', 'account'],
+
 	requireCredential: true,
 
 	kind: 'account-read',
diff --git a/src/server/api/endpoints/users/lists/update.ts b/src/server/api/endpoints/users/lists/update.ts
index 842ae189ee..5897693144 100644
--- a/src/server/api/endpoints/users/lists/update.ts
+++ b/src/server/api/endpoints/users/lists/update.ts
@@ -10,6 +10,8 @@ export const meta = {
 		'en-US': 'Update a user list'
 	},
 
+	tags: ['lists'],
+
 	requireCredential: true,
 
 	kind: 'account-write',
diff --git a/src/server/api/endpoints/users/notes.ts b/src/server/api/endpoints/users/notes.ts
index 1c5882d5b2..f8942fb2d3 100644
--- a/src/server/api/endpoints/users/notes.ts
+++ b/src/server/api/endpoints/users/notes.ts
@@ -11,6 +11,8 @@ export const meta = {
 		'ja-JP': '指定したユーザーのタイムラインを取得します。'
 	},
 
+	tags: ['users', 'notes'],
+
 	params: {
 		userId: {
 			validator: $.type(ID),
@@ -124,6 +126,13 @@ export const meta = {
 		},
 	},
 
+	res: {
+		type: 'array',
+		items: {
+			type: 'Note',
+		},
+	},
+
 	errors: {
 		noSuchUser: {
 			message: 'No such user.',
diff --git a/src/server/api/endpoints/users/recommendation.ts b/src/server/api/endpoints/users/recommendation.ts
index dc37bc56ba..2261ee7df4 100644
--- a/src/server/api/endpoints/users/recommendation.ts
+++ b/src/server/api/endpoints/users/recommendation.ts
@@ -15,6 +15,8 @@ export const meta = {
 		'ja-JP': 'おすすめのユーザー一覧を取得します。'
 	},
 
+	tags: ['users'],
+
 	requireCredential: true,
 
 	kind: 'account-read',
diff --git a/src/server/api/endpoints/users/relation.ts b/src/server/api/endpoints/users/relation.ts
index 5b7b4d8e4d..f4121aa0d0 100644
--- a/src/server/api/endpoints/users/relation.ts
+++ b/src/server/api/endpoints/users/relation.ts
@@ -8,11 +8,13 @@ export const meta = {
 		'ja-JP': 'ユーザー間のリレーションを取得します。'
 	},
 
+	tags: ['users'],
+
 	requireCredential: true,
 
 	params: {
 		userId: {
-			validator: $.or($.type(ID), $.arr($.type(ID)).unique()),
+			validator: $.either($.type(ID), $.arr($.type(ID)).unique()),
 			transform: (v: any): ObjectId | ObjectId[] => Array.isArray(v) ? v.map(x => transform(x)) : transform(v),
 			desc: {
 				'ja-JP': 'ユーザーID (配列でも可)'
diff --git a/src/server/api/endpoints/users/report-abuse.ts b/src/server/api/endpoints/users/report-abuse.ts
index 36f797f5e6..0f23f8f0c3 100644
--- a/src/server/api/endpoints/users/report-abuse.ts
+++ b/src/server/api/endpoints/users/report-abuse.ts
@@ -12,6 +12,8 @@ export const meta = {
 		'ja-JP': '指定したユーザーを迷惑なユーザーであると報告します。'
 	},
 
+	tags: ['users'],
+
 	requireCredential: true,
 
 	params: {
diff --git a/src/server/api/endpoints/users/search.ts b/src/server/api/endpoints/users/search.ts
index 6fd390f283..a6b50b687f 100644
--- a/src/server/api/endpoints/users/search.ts
+++ b/src/server/api/endpoints/users/search.ts
@@ -8,6 +8,8 @@ export const meta = {
 		'ja-JP': 'ユーザーを検索します。'
 	},
 
+	tags: ['users'],
+
 	requireCredential: false,
 
 	params: {
diff --git a/src/server/api/endpoints/users/show.ts b/src/server/api/endpoints/users/show.ts
index 4f870b8b92..4e59945eba 100644
--- a/src/server/api/endpoints/users/show.ts
+++ b/src/server/api/endpoints/users/show.ts
@@ -13,6 +13,8 @@ export const meta = {
 		'ja-JP': '指定したユーザーの情報を取得します。'
 	},
 
+	tags: ['users'],
+
 	requireCredential: false,
 
 	params: {
@@ -42,6 +44,10 @@ export const meta = {
 		}
 	},
 
+	res: {
+		type: 'User',
+	},
+
 	errors: {
 		failedToResolveRemoteUser: {
 			message: 'Failed to resolve remote user.',