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

25 files changed, 144 insertions, 6 deletions

diff --git a/src/server/api/endpoints/notes/conversation.ts b/src/server/api/endpoints/notes/conversation.ts
index 2f08de9e8f..702d8dc430 100644
--- a/src/server/api/endpoints/notes/conversation.ts
+++ b/src/server/api/endpoints/notes/conversation.ts
@@ -11,6 +11,8 @@ export const meta = {
 		'en-US': 'Show conversation of a note.'
 	},
 
+	tags: ['notes'],
+
 	requireCredential: false,
 
 	params: {
@@ -34,6 +36,13 @@ export const meta = {
 		},
 	},
 
+	res: {
+		type: 'array',
+		items: {
+			type: 'Note',
+		},
+	},
+
 	errors: {
 		noSuchNote: {
 			message: 'No such note.',
diff --git a/src/server/api/endpoints/notes/create.ts b/src/server/api/endpoints/notes/create.ts
index d24cd7b123..a4f262bdad 100644
--- a/src/server/api/endpoints/notes/create.ts
+++ b/src/server/api/endpoints/notes/create.ts
@@ -25,6 +25,8 @@ export const meta = {
 		'ja-JP': '投稿します。'
 	},
 
+	tags: ['notes'],
+
 	requireCredential: true,
 
 	limit: {
@@ -175,7 +177,7 @@ export const meta = {
 		type: 'object',
 		props: {
 			createdNote: {
-				type: 'entity(Note)',
+				type: 'Note',
 				desc: {
 					'ja-JP': '作成した投稿'
 				}
diff --git a/src/server/api/endpoints/notes/delete.ts b/src/server/api/endpoints/notes/delete.ts
index 8ca5a3bb08..399f9288d6 100644
--- a/src/server/api/endpoints/notes/delete.ts
+++ b/src/server/api/endpoints/notes/delete.ts
@@ -15,6 +15,8 @@ export const meta = {
 		'en-US': 'Delete a note.'
 	},
 
+	tags: ['notes'],
+
 	requireCredential: true,
 
 	kind: 'note-write',
diff --git a/src/server/api/endpoints/notes/favorites/create.ts b/src/server/api/endpoints/notes/favorites/create.ts
index 26e3e34d55..9cde1a7dcf 100644
--- a/src/server/api/endpoints/notes/favorites/create.ts
+++ b/src/server/api/endpoints/notes/favorites/create.ts
@@ -13,6 +13,8 @@ export const meta = {
 		'en-US': 'Favorite a note.'
 	},
 
+	tags: ['favorites'],
+
 	requireCredential: true,
 
 	kind: 'favorite-write',
diff --git a/src/server/api/endpoints/notes/favorites/delete.ts b/src/server/api/endpoints/notes/favorites/delete.ts
index d79a3d88cb..e2c787f3b5 100644
--- a/src/server/api/endpoints/notes/favorites/delete.ts
+++ b/src/server/api/endpoints/notes/favorites/delete.ts
@@ -13,6 +13,8 @@ export const meta = {
 		'en-US': 'Unfavorite a note.'
 	},
 
+	tags: ['favorites'],
+
 	requireCredential: true,
 
 	kind: 'favorite-write',
diff --git a/src/server/api/endpoints/notes/featured.ts b/src/server/api/endpoints/notes/featured.ts
index 08cc677abd..0d2187bb06 100644
--- a/src/server/api/endpoints/notes/featured.ts
+++ b/src/server/api/endpoints/notes/featured.ts
@@ -10,6 +10,8 @@ export const meta = {
 		'en-US': 'Get featured notes.'
 	},
 
+	tags: ['notes'],
+
 	requireCredential: false,
 
 	params: {
@@ -20,7 +22,14 @@ export const meta = {
 				'ja-JP': '最大数'
 			}
 		}
-	}
+	},
+
+	res: {
+		type: 'array',
+		items: {
+			type: 'Note',
+		},
+	},
 };
 
 export default define(meta, async (ps, user) => {
diff --git a/src/server/api/endpoints/notes/global-timeline.ts b/src/server/api/endpoints/notes/global-timeline.ts
index 8670f8edbb..b62d8e25a3 100644
--- a/src/server/api/endpoints/notes/global-timeline.ts
+++ b/src/server/api/endpoints/notes/global-timeline.ts
@@ -12,6 +12,8 @@ export const meta = {
 		'ja-JP': 'グローバルタイムラインを取得します。'
 	},
 
+	tags: ['notes'],
+
 	params: {
 		withFiles: {
 			validator: $.optional.bool,
@@ -51,6 +53,13 @@ export const meta = {
 		},
 	},
 
+	res: {
+		type: 'array',
+		items: {
+			type: 'Note',
+		},
+	},
+
 	errors: {
 		gtlDisabled: {
 			message: 'Global timeline has been disabled.',
diff --git a/src/server/api/endpoints/notes/hybrid-timeline.ts b/src/server/api/endpoints/notes/hybrid-timeline.ts
index f3050caeca..153436b9bb 100644
--- a/src/server/api/endpoints/notes/hybrid-timeline.ts
+++ b/src/server/api/endpoints/notes/hybrid-timeline.ts
@@ -14,6 +14,8 @@ export const meta = {
 		'ja-JP': 'ハイブリッドタイムラインを取得します。'
 	},
 
+	tags: ['notes'],
+
 	params: {
 		limit: {
 			validator: $.optional.num.range(1, 100),
@@ -92,6 +94,13 @@ export const meta = {
 		},
 	},
 
+	res: {
+		type: 'array',
+		items: {
+			type: 'Note',
+		},
+	},
+
 	errors: {
 		stlDisabled: {
 			message: 'Social timeline has been disabled.',
diff --git a/src/server/api/endpoints/notes/local-timeline.ts b/src/server/api/endpoints/notes/local-timeline.ts
index 44328ebede..06c6d7a533 100644
--- a/src/server/api/endpoints/notes/local-timeline.ts
+++ b/src/server/api/endpoints/notes/local-timeline.ts
@@ -13,6 +13,8 @@ export const meta = {
 		'ja-JP': 'ローカルタイムラインを取得します。'
 	},
 
+	tags: ['notes'],
+
 	params: {
 		withFiles: {
 			validator: $.optional.bool,
@@ -67,6 +69,13 @@ export const meta = {
 		},
 	},
 
+	res: {
+		type: 'array',
+		items: {
+			type: 'Note',
+		},
+	},
+
 	errors: {
 		ltlDisabled: {
 			message: 'Local timeline has been disabled.',
diff --git a/src/server/api/endpoints/notes/mentions.ts b/src/server/api/endpoints/notes/mentions.ts
index 090f184f7b..91333174ed 100644
--- a/src/server/api/endpoints/notes/mentions.ts
+++ b/src/server/api/endpoints/notes/mentions.ts
@@ -13,6 +13,8 @@ export const meta = {
 		'en-US': 'Get mentions of myself.'
 	},
 
+	tags: ['notes'],
+
 	requireCredential: true,
 
 	params: {
@@ -39,7 +41,14 @@ export const meta = {
 		visibility: {
 			validator: $.optional.str,
 		},
-	}
+	},
+
+	res: {
+		type: 'array',
+		items: {
+			type: 'Note',
+		},
+	},
 };
 
 export default define(meta, async (ps, user) => {
diff --git a/src/server/api/endpoints/notes/polls/recommendation.ts b/src/server/api/endpoints/notes/polls/recommendation.ts
index 61a1840b88..0a05e89c6f 100644
--- a/src/server/api/endpoints/notes/polls/recommendation.ts
+++ b/src/server/api/endpoints/notes/polls/recommendation.ts
@@ -10,6 +10,8 @@ export const meta = {
 		'en-US': 'Get recommended polls.'
 	},
 
+	tags: ['notes'],
+
 	requireCredential: true,
 
 	params: {
diff --git a/src/server/api/endpoints/notes/polls/vote.ts b/src/server/api/endpoints/notes/polls/vote.ts
index 00840579dd..60007db136 100644
--- a/src/server/api/endpoints/notes/polls/vote.ts
+++ b/src/server/api/endpoints/notes/polls/vote.ts
@@ -18,6 +18,8 @@ export const meta = {
 		'en-US': 'Vote poll of a note.'
 	},
 
+	tags: ['notes'],
+
 	requireCredential: true,
 
 	kind: 'vote-write',
diff --git a/src/server/api/endpoints/notes/reactions.ts b/src/server/api/endpoints/notes/reactions.ts
index 74f22cc774..c67dd6d82b 100644
--- a/src/server/api/endpoints/notes/reactions.ts
+++ b/src/server/api/endpoints/notes/reactions.ts
@@ -11,6 +11,8 @@ export const meta = {
 		'en-US': 'Show reactions of a note.'
 	},
 
+	tags: ['notes', 'reactions'],
+
 	requireCredential: false,
 
 	params: {
diff --git a/src/server/api/endpoints/notes/reactions/create.ts b/src/server/api/endpoints/notes/reactions/create.ts
index 816c6a9c29..291e10bbd0 100644
--- a/src/server/api/endpoints/notes/reactions/create.ts
+++ b/src/server/api/endpoints/notes/reactions/create.ts
@@ -14,6 +14,8 @@ export const meta = {
 		'en-US': 'React to a note.'
 	},
 
+	tags: ['reactions', 'notes'],
+
 	requireCredential: true,
 
 	kind: 'reaction-write',
diff --git a/src/server/api/endpoints/notes/reactions/delete.ts b/src/server/api/endpoints/notes/reactions/delete.ts
index 1afa6526f5..2ccfb93293 100644
--- a/src/server/api/endpoints/notes/reactions/delete.ts
+++ b/src/server/api/endpoints/notes/reactions/delete.ts
@@ -12,6 +12,8 @@ export const meta = {
 		'en-US': 'Unreact to a note.'
 	},
 
+	tags: ['reactions', 'notes'],
+
 	requireCredential: true,
 
 	kind: 'reaction-write',
diff --git a/src/server/api/endpoints/notes/renotes.ts b/src/server/api/endpoints/notes/renotes.ts
index b4c99b1f4e..15dcf55dce 100644
--- a/src/server/api/endpoints/notes/renotes.ts
+++ b/src/server/api/endpoints/notes/renotes.ts
@@ -11,6 +11,8 @@ export const meta = {
 		'en-US': 'Show a renotes of a note.'
 	},
 
+	tags: ['notes'],
+
 	requireCredential: false,
 
 	params: {
@@ -39,6 +41,13 @@ export const meta = {
 		}
 	},
 
+	res: {
+		type: 'array',
+		items: {
+			type: 'Note',
+		},
+	},
+
 	errors: {
 		noSuchNote: {
 			message: 'No such note.',
diff --git a/src/server/api/endpoints/notes/replies.ts b/src/server/api/endpoints/notes/replies.ts
index 080917f6f6..c80fd73205 100644
--- a/src/server/api/endpoints/notes/replies.ts
+++ b/src/server/api/endpoints/notes/replies.ts
@@ -11,6 +11,8 @@ export const meta = {
 		'en-US': 'Get replies of a note.'
 	},
 
+	tags: ['notes'],
+
 	requireCredential: false,
 
 	params: {
@@ -32,7 +34,14 @@ export const meta = {
 			validator: $.optional.num.min(0),
 			default: 0
 		},
-	}
+	},
+
+	res: {
+		type: 'array',
+		items: {
+			type: 'Note',
+		},
+	},
 };
 
 export default define(meta, async (ps, user) => {
diff --git a/src/server/api/endpoints/notes/search.ts b/src/server/api/endpoints/notes/search.ts
index 3eec2e3189..edc8a14560 100644
--- a/src/server/api/endpoints/notes/search.ts
+++ b/src/server/api/endpoints/notes/search.ts
@@ -12,6 +12,8 @@ export const meta = {
 		'en-US': 'Search notes.'
 	},
 
+	tags: ['notes'],
+
 	requireCredential: false,
 
 	params: {
@@ -30,6 +32,13 @@ export const meta = {
 		}
 	},
 
+	res: {
+		type: 'array',
+		items: {
+			type: 'Note',
+		},
+	},
+
 	errors: {
 		searchingNotAvailable: {
 			message: 'Searching not available.',
diff --git a/src/server/api/endpoints/notes/search_by_tag.ts b/src/server/api/endpoints/notes/search_by_tag.ts
index a4fd1903ef..0030e2e37a 100644
--- a/src/server/api/endpoints/notes/search_by_tag.ts
+++ b/src/server/api/endpoints/notes/search_by_tag.ts
@@ -11,6 +11,8 @@ export const meta = {
 		'ja-JP': '指定されたタグが付けられた投稿を取得します。'
 	},
 
+	tags: ['notes', 'hashtags'],
+
 	params: {
 		tag: {
 			validator: $.optional.str,
@@ -100,7 +102,14 @@ export const meta = {
 			validator: $.optional.num.range(1, 30),
 			default: 10
 		},
-	}
+	},
+
+	res: {
+		type: 'array',
+		items: {
+			type: 'Note',
+		},
+	},
 };
 
 export default define(meta, async (ps, me) => {
diff --git a/src/server/api/endpoints/notes/show.ts b/src/server/api/endpoints/notes/show.ts
index f4fd06c03d..6d8dc73ff2 100644
--- a/src/server/api/endpoints/notes/show.ts
+++ b/src/server/api/endpoints/notes/show.ts
@@ -13,6 +13,8 @@ export const meta = {
 		'en-US': 'Get a note.'
 	},
 
+	tags: ['notes'],
+
 	requireCredential: false,
 
 	params: {
@@ -26,6 +28,10 @@ export const meta = {
 		}
 	},
 
+	res: {
+		type: 'Note',
+	},
+
 	errors: {
 		noSuchNote: {
 			message: 'No such note.',
diff --git a/src/server/api/endpoints/notes/state.ts b/src/server/api/endpoints/notes/state.ts
index 07e35480fd..4944802849 100644
--- a/src/server/api/endpoints/notes/state.ts
+++ b/src/server/api/endpoints/notes/state.ts
@@ -12,6 +12,8 @@ export const meta = {
 		'en-US': 'Get state of a note.'
 	},
 
+	tags: ['notes'],
+
 	requireCredential: true,
 
 	params: {
diff --git a/src/server/api/endpoints/notes/timeline.ts b/src/server/api/endpoints/notes/timeline.ts
index cb6900a10b..9ec8070f71 100644
--- a/src/server/api/endpoints/notes/timeline.ts
+++ b/src/server/api/endpoints/notes/timeline.ts
@@ -13,6 +13,8 @@ export const meta = {
 		'en-US': 'Get timeline of myself.'
 	},
 
+	tags: ['notes'],
+
 	requireCredential: true,
 
 	params: {
@@ -91,7 +93,14 @@ export const meta = {
 				'ja-JP': 'true にすると、ファイルが添付された投稿だけ取得します (このパラメータは廃止予定です。代わりに withFiles を使ってください。)'
 			}
 		},
-	}
+	},
+
+	res: {
+		type: 'array',
+		items: {
+			type: 'Note',
+		},
+	},
 };
 
 export default define(meta, async (ps, user) => {
diff --git a/src/server/api/endpoints/notes/user-list-timeline.ts b/src/server/api/endpoints/notes/user-list-timeline.ts
index 1969b924ad..45e96fbdac 100644
--- a/src/server/api/endpoints/notes/user-list-timeline.ts
+++ b/src/server/api/endpoints/notes/user-list-timeline.ts
@@ -14,6 +14,8 @@ export const meta = {
 		'en-US': 'Get timeline of a user list.'
 	},
 
+	tags: ['notes', 'lists'],
+
 	requireCredential: true,
 
 	params: {
@@ -102,6 +104,13 @@ export const meta = {
 		},
 	},
 
+	res: {
+		type: 'array',
+		items: {
+			type: 'Note',
+		},
+	},
+
 	errors: {
 		noSuchList: {
 			message: 'No such list.',
diff --git a/src/server/api/endpoints/notes/watching/create.ts b/src/server/api/endpoints/notes/watching/create.ts
index 7361237e8d..2b2de1bd3b 100644
--- a/src/server/api/endpoints/notes/watching/create.ts
+++ b/src/server/api/endpoints/notes/watching/create.ts
@@ -13,6 +13,8 @@ export const meta = {
 		'en-US': 'Watch a note.'
 	},
 
+	tags: ['notes'],
+
 	requireCredential: true,
 
 	kind: 'account-write',
diff --git a/src/server/api/endpoints/notes/watching/delete.ts b/src/server/api/endpoints/notes/watching/delete.ts
index 33fbef570c..512db793ea 100644
--- a/src/server/api/endpoints/notes/watching/delete.ts
+++ b/src/server/api/endpoints/notes/watching/delete.ts
@@ -13,6 +13,8 @@ export const meta = {
 		'en-US': 'Unwatch a note.'
 	},
 
+	tags: ['notes'],
+
 	requireCredential: true,
 
 	kind: 'account-write',