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

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: {

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: {

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: {

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

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

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'

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

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

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

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

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

src/server/api/endpoints/users/recommendation.ts

@@ -15,6 +15,8 @@ export const meta = {
 		'ja-JP': 'おすすめのユーザー一覧を取得します。'
 	},
 
+	tags: ['users'],
+
 	requireCredential: true,
 
 	kind: 'account-read',

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 (配列でも可)'

src/server/api/endpoints/users/report-abuse.ts

@@ -12,6 +12,8 @@ export const meta = {
 		'ja-JP': '指定したユーザーを迷惑なユーザーであると報告します。'
 	},
 
+	tags: ['users'],
+
 	requireCredential: true,
 
 	params: {

src/server/api/endpoints/users/search.ts

@@ -8,6 +8,8 @@ export const meta = {
 		'ja-JP': 'ユーザーを検索します。'
 	},
 
+	tags: ['users'],
+
 	requireCredential: false,
 
 	params: {

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