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>

3 files changed, 268 insertions, 1 deletions

diff --git a/src/server/api/endpoints/games/reversi/games.ts b/src/server/api/endpoints/games/reversi/games.ts
index 7267157e0e..fa8bf20353 100644
--- a/src/server/api/endpoints/games/reversi/games.ts
+++ b/src/server/api/endpoints/games/reversi/games.ts
@@ -26,6 +26,113 @@ export const meta = {
 			validator: $.optional.bool,
 			default: false
 		}
+	},
+
+	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'
+				},
+				startedAt: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					format: 'date-time'
+				},
+				isStarted: {
+					type: 'boolean' as const,
+					optional: false as const, nullable: false as const
+				},
+				isEnded: {
+					type: 'boolean' as const,
+					optional: false as const, nullable: false as const
+				},
+				form1: {
+					type: 'any' as const,
+					optional: false as const, nullable: true as const
+				},
+				form2: {
+					type: 'any' as const,
+					optional: false as const, nullable: true as const
+				},
+				user1Accepted: {
+					type: 'boolean' as const,
+					optional: false as const, nullable: false as const,
+					default: false
+				},
+				user2Accepted: {
+					type: 'boolean' as const,
+					optional: false as const, nullable: false as const,
+					default: false
+				},
+				user1Id: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					format: 'id'
+				},
+				user2Id: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					format: 'id'
+				},
+				user1: {
+					type: 'object' as const,
+					optional: false as const, nullable: false as const,
+					ref: 'User'
+				},
+				user2: {
+					type: 'object' as const,
+					optional: false as const, nullable: false as const,
+					ref: 'User'
+				},
+				winnerId: {
+					type: 'string' as const,
+					optional: false as const, nullable: true as const,
+					format: 'id'
+				},
+				winner: {
+					type: 'object' as const,
+					optional: false as const, nullable: true as const,
+					ref: 'User'
+				},
+				surrendered: {
+					type: 'string' as const,
+					optional: false as const, nullable: true as const,
+					format: 'id'
+				},
+				black: {
+					type: 'number' as const,
+					optional: false as const, nullable: true as const
+				},
+				bw: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const
+				},
+				isLlotheo: {
+					type: 'boolean' as const,
+					optional: false as const, nullable: false as const,
+				},
+				canPutEverywhere: {
+					type: 'boolean' as const,
+					optional: false as const, nullable: false as const
+				},
+				loopedBoard: {
+					type: 'boolean' as const,
+					optional: false as const, nullable: false as const
+				}
+			}
+		}
 	}
 };
 
diff --git a/src/server/api/endpoints/games/reversi/games/show.ts b/src/server/api/endpoints/games/reversi/games/show.ts
index ea2776b16f..75599885c9 100644
--- a/src/server/api/endpoints/games/reversi/games/show.ts
+++ b/src/server/api/endpoints/games/reversi/games/show.ts
@@ -20,6 +20,125 @@ export const meta = {
 			code: 'NO_SUCH_GAME',
 			id: 'f13a03db-fae1-46c9-87f3-43c8165419e1'
 		},
+	},
+
+	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'
+				},
+				startedAt: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					format: 'date-time'
+				},
+				isStarted: {
+					type: 'boolean' as const,
+					optional: false as const, nullable: false as const
+				},
+				isEnded: {
+					type: 'boolean' as const,
+					optional: false as const, nullable: false as const
+				},
+				form1: {
+					type: 'any' as const,
+					optional: false as const, nullable: true as const
+				},
+				form2: {
+					type: 'any' as const,
+					optional: false as const, nullable: true as const
+				},
+				user1Accepted: {
+					type: 'boolean' as const,
+					optional: false as const, nullable: false as const,
+					default: false
+				},
+				user2Accepted: {
+					type: 'boolean' as const,
+					optional: false as const, nullable: false as const,
+					default: false
+				},
+				user1Id: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					format: 'id'
+				},
+				user2Id: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					format: 'id'
+				},
+				user1: {
+					type: 'object' as const,
+					optional: false as const, nullable: false as const,
+					ref: 'User'
+				},
+				user2: {
+					type: 'object' as const,
+					optional: false as const, nullable: false as const,
+					ref: 'User'
+				},
+				winnerId: {
+					type: 'string' as const,
+					optional: false as const, nullable: true as const,
+					format: 'id'
+				},
+				winner: {
+					type: 'object' as const,
+					optional: false as const, nullable: true as const,
+					ref: 'User'
+				},
+				surrendered: {
+					type: 'string' as const,
+					optional: false as const, nullable: true as const,
+					format: 'id'
+				},
+				black: {
+					type: 'number' as const,
+					optional: false as const, nullable: true as const
+				},
+				bw: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const
+				},
+				isLlotheo: {
+					type: 'boolean' as const,
+					optional: false as const, nullable: false as const,
+				},
+				canPutEverywhere: {
+					type: 'boolean' as const,
+					optional: false as const, nullable: false as const
+				},
+				loopedBoard: {
+					type: 'boolean' as const,
+					optional: false as const, nullable: false as const
+				},
+				board: {
+					type: 'array' as const,
+					optional: false as const, nullable: false as const,
+					items: {
+						type: 'any' as const,
+						optional: false as const, nullable: false as const
+					}
+				},
+				turn: {
+					type: 'any' as const,
+					optional: false as const, nullable: false as const
+				}
+			}
+		}
 	}
 };
 
diff --git a/src/server/api/endpoints/games/reversi/invitations.ts b/src/server/api/endpoints/games/reversi/invitations.ts
index 93ea1bd58e..6a73bdf0c4 100644
--- a/src/server/api/endpoints/games/reversi/invitations.ts
+++ b/src/server/api/endpoints/games/reversi/invitations.ts
@@ -4,7 +4,48 @@ import { ReversiMatchings } from '../../../../../models';
 export const meta = {
 	tags: ['games'],
 
-	requireCredential: true as const
+	requireCredential: true as const,
+
+	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'
+				},
+				parentId: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					format: 'id'
+				},
+				parent: {
+					type: 'object' as const,
+					optional: false as const, nullable: false as const,
+					ref: 'User'
+				},
+				childId: {
+					type: 'string' as const,
+					optional: false as const, nullable: false as const,
+					format: 'id'
+				},
+				child: {
+					type: 'object' as const,
+					optional: false as const, nullable: false as const,
+					ref: 'User'
+				}
+			}
+		}
+	}
 };
 
 export default define(meta, async (ps, user) => {