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/models/repositories/antenna.ts

@@ -41,20 +41,78 @@ export const packedAntennaSchema = {
 		id: {
 			type: 'string' as const,
 			optional: false as const, nullable: false as const,
-			format: 'id',
-			description: 'The unique identifier for this Antenna.',
-			example: 'xxxxxxxxxx',
+			format: 'id'
 		},
 		createdAt: {
 			type: 'string' as const,
 			optional: false as const, nullable: false as const,
-			format: 'date-time',
-			description: 'The date that the Antenna was created.'
+			format: 'date-time'
 		},
 		name: {
 			type: 'string' as const,
-			optional: false as const, nullable: false as const,
-			description: 'The name of the Antenna.'
+			optional: false as const, nullable: false as const
 		},
+		keywords: {
+			type: 'array' as const,
+			optional: false as const, nullable: false as const,
+			items: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const
+			}
+		},
+		execludeKeywords: {
+			type: 'array' as const,
+			optional: false as const, nullable: false as const,
+			items: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const
+			}
+		},
+		src: {
+			type: 'string' as const,
+			optional: false as const, nullable: false as const,
+			enum: ['home', 'all', 'users', 'list', 'group']
+		},
+		userListId: {
+			type: 'string' as const,
+			optional: false as const, nullable: true as const,
+			format: 'id'
+		},
+		userGroupId: {
+			type: 'string' as const,
+			optional: false as const, nullable: true as const,
+			format: 'id'
+		},
+		users: {
+			type: 'array' as const,
+			optional: false as const, nullable: false as const,
+			items: {
+				type: 'string' as const,
+				optional: false as const, nullable: false as const
+			}
+		},
+		caseSensitive: {
+			type: 'boolean' as const,
+			optional: false as const, nullable: false as const,
+			default: false
+		},
+		notify: {
+			type: 'boolean' as const,
+			optional: false as const, nullable: false as const
+		},
+		withReplies: {
+			type: 'boolean' as const,
+			optional: false as const, nullable: false as const,
+			default: false
+		},
+		withFile: {
+			type: 'boolean' as const,
+			optional: false as const, nullable: false as const
+		},
+		hasUnreadNote: {
+			type: 'boolean' as const,
+			optional: false as const, nullable: false as const,
+			default: false
+		}
 	},
 };

src/models/repositories/app.ts

@@ -46,33 +46,35 @@ export const packedAppSchema = {
 	properties: {
 		id: {
 			type: 'string' as const,
-			optional: false as const, nullable: false as const,
-			format: 'id',
-			description: 'The unique identifier for this Note.',
-			example: 'xxxxxxxxxx',
+			optional: false as const, nullable: false as const
 		},
 		name: {
 			type: 'string' as const,
-			optional: false as const, nullable: false as const,
-			description: 'アプリケーションの名前'
+			optional: false as const, nullable: false as const
 		},
-		callbackUrl: {
+		createdAt: {
 			type: 'string' as const,
-			optional: false as const, nullable: true as const,
-			description: 'コールバックするURL'
+			optional: false as const, nullable: false as const
+		},
+		lastUsedAt: {
+			type: 'string' as const,
+			optional: false as const, nullable: false as const
 		},
 		permission: {
 			type: 'array' as const,
-			optional: true as const, nullable: false as const,
+			optional: false as const, nullable: false as const,
 			items: {
 				type: 'string' as const,
-				optional: false as const, nullable: false as const,
+				optional: false as const, nullable: false as const
 			}
 		},
 		secret: {
 			type: 'string' as const,
-			optional: true as const, nullable: false as const,
-			description: 'アプリケーションのシークレットキー'
+			optional: true as const, nullable: false as const
+		},
+		isAuthorized: {
+			type: 'boolean' as const,
+			optional: true as const, nullable: false as const
 		}
-	},
+	}
 };

src/models/repositories/drive-file.ts

@@ -182,12 +182,52 @@ export const packedDriveFileSchema = {
 			description: 'The size of this Drive file. (bytes)',
 			example: 51469
 		},
+		isSensitive: {
+			type: 'boolean' as const,
+			optional: false as const, nullable: false as const,
+			description: 'Whether this Drive file is sensitive.',
+		},
+		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)'
+				}
+			}
+		},
 		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.',
+		},
+		comment: {
+			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,
@@ -195,10 +235,24 @@ export const packedDriveFileSchema = {
 			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.',
+		folder: {
+			type: 'object' as const,
+			optional: true as const, nullable: true as const,
+			description: 'The parent folder of this Drive file.',
+			ref: 'DriveFolder'
 		},
+		userId: {
+			type: 'string' as const,
+			optional: false as const, nullable: true as const,
+			format: 'id',
+			description: 'Owner ID of this Drive file.',
+			example: 'xxxxxxxxxx',
+		},
+		user: {
+			type: 'object' as const,
+			optional: true as const, nullable: true as const,
+			description: 'Owner of this Drive file.',
+			ref: 'User'
+		}
 	},
 };

src/models/repositories/federation-instance.ts

@@ -0,0 +1,106 @@
+import config from '../../config';
+
+export const packedFederationInstanceSchema = {
+	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'
+		},
+		caughtAt: {
+			type: 'string' as const,
+			optional: false as const, nullable: false as const,
+			format: 'date-time'
+		},
+		host: {
+			type: 'string' as const,
+			optional: false as const, nullable: false as const,
+			example: 'misskey.example.com'
+		},
+		usersCount: {
+			type: 'number' as const,
+			optional: false as const, nullable: false as const
+		},
+		notesCount: {
+			type: 'number' as const,
+			optional: false as const, nullable: false as const
+		},
+		followingCount: {
+			type: 'number' as const,
+			optional: false as const, nullable: false as const
+		},
+		followersCount: {
+			type: 'number' as const,
+			optional: false as const, nullable: false as const
+		},
+		driveUsage: {
+			type: 'number' as const,
+			optional: false as const, nullable: false as const
+		},
+		driveFiles: {
+			type: 'number' as const,
+			optional: false as const, nullable: false as const
+		},
+		latestRequestSentAt: {
+			type: 'string' as const,
+			optional: false as const, nullable: true as const,
+			format: 'date-time'
+		},
+		lastCommunicatedAt: {
+			type: 'string' as const,
+			optional: false as const, nullable: false as const,
+			format: 'date-time'
+		},
+		isNotResponding: {
+			type: 'boolean' as const,
+			optional: false as const, nullable: false as const
+		},
+		isSuspended: {
+			type: 'boolean' as const,
+			optional: false as const, nullable: false as const
+		},
+		softwareName: {
+			type: 'string' as const,
+			optional: false as const, nullable: true as const,
+			example: 'misskey'
+		},
+		softwareVersion: {
+			type: 'string' as const,
+			optional: false as const, nullable: true as const,
+			example: config.version
+		},
+		openRegistrations: {
+			type: 'boolean' as const,
+			optional: false as const, nullable: true as const,
+			example: true
+		},
+		name: {
+			type: 'string' as const,
+			optional: false as const, nullable: true as const
+		},
+		description: {
+			type: 'string' as const,
+			optional: false as const, nullable: true as const
+		},
+		maintainerName: {
+			type: 'string' as const,
+			optional: false as const, nullable: true as const
+		},
+		maintainerEmail: {
+			type: 'string' as const,
+			optional: false as const, nullable: true as const
+		},
+		iconUrl: {
+			type: 'string' as const,
+			optional: false as const, nullable: true as const,
+			format: 'url'
+		},
+		infoUpdatedAt: {
+			type: 'string' as const,
+			optional: false as const, nullable: true as const,
+			format: 'date-time'
+		}
+	}
+};

src/models/repositories/queue.ts

@@ -0,0 +1,30 @@
+export const packedQueueCountSchema = {
+	type: 'object' as const,
+	optional: false as const, nullable: false as const,
+	properties: {
+		waiting: {
+			type: 'number' as const,
+			optional: false as const, nullable: false as const
+		},
+		active: {
+			type: 'number' as const,
+			optional: false as const, nullable: false as const
+		},
+		completed: {
+			type: 'number' as const,
+			optional: false as const, nullable: false as const
+		},
+		failed: {
+			type: 'number' as const,
+			optional: false as const, nullable: false as const
+		},
+		delayed: {
+			type: 'number' as const,
+			optional: false as const, nullable: false as const
+		},
+		paused: {
+			type: 'number' as const,
+			optional: false as const, nullable: false as const
+		}
+	}
+};

src/models/repositories/user.ts

@@ -330,22 +330,22 @@ export const packedUserSchema = {
 			description: 'The unique identifier for this User.',
 			example: 'xxxxxxxxxx',
 		},
-		username: {
-			type: 'string' as const,
-			nullable: false as const, optional: false as const,
-			description: 'The screen name, handle, or alias that this user identifies themselves with.',
-			example: 'ai'
-		},
 		name: {
 			type: 'string' as const,
 			nullable: true as const, optional: false as const,
 			description: 'The name of the user, as they’ve defined it.',
 			example: '藍'
 		},
-		url: {
+		username: {
 			type: 'string' as const,
-			format: 'url',
-			nullable: true as const, optional: true as const,
+			nullable: false as const, optional: false as const,
+			description: 'The screen name, handle, or alias that this user identifies themselves with.',
+			example: 'ai'
+		},
+		host: {
+			type: 'string' as const,
+			nullable: true as const, optional: false as const,
+			example: 'misskey.example.com'
 		},
 		avatarUrl: {
 			type: 'string' as const,
@@ -356,35 +356,69 @@ export const packedUserSchema = {
 			type: 'any' as const,
 			nullable: true as const, optional: false as const,
 		},
-		bannerUrl: {
+		avatarColor: {
+			type: 'any' as const,
+			nullable: true as const, optional: false as const,
+			default: null
+		},
+		isAdmin: {
+			type: 'boolean' as const,
+			nullable: false as const, optional: false as const,
+			description: 'Whether this account is the admin.',
+			default: false
+		},
+		isModerator: {
+			type: 'boolean' as const,
+			nullable: false as const, optional: false as const,
+			description: 'Whether this account is a moderator.',
+			default: false
+		},
+		isBot: {
+			type: 'boolean' as const,
+			nullable: false as const, optional: true as const,
+			description: 'Whether this account is a bot.'
+		},
+		isCat: {
+			type: 'boolean' as const,
+			nullable: false as const, optional: true as const,
+			description: 'Whether this account is a cat.'
+		},
+		emojis: {
+			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,
+				properties: {
+					name: {
+						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
+					},
+					url: {
+						type: 'string' as const,
+						nullable: false as const, optional: false as const,
+						format: 'url'
+					},
+					aliases: {
+						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
+						}
+					}
+				}
+			}
+		},
+		url: {
 			type: 'string' as const,
 			format: 'url',
 			nullable: true as const, optional: true as const,
 		},
-		bannerBlurhash: {
-			type: 'any' as const,
-			nullable: true as const, optional: true as const,
-		},
-		emojis: {
-			type: 'any' as const,
-			nullable: true as const, optional: false as const,
-		},
-		host: {
-			type: 'string' as const,
-			nullable: true as const, optional: false as const,
-			example: 'misskey.example.com'
-		},
-		description: {
-			type: 'string' as const,
-			nullable: true as const, optional: true as const,
-			description: 'The user-defined UTF-8 string describing their account.',
-			example: 'Hi masters, I am Ai!'
-		},
-		birthday: {
-			type: 'string' as const,
-			nullable: true as const, optional: true as const,
-			example: '2018-03-12'
-		},
 		createdAt: {
 			type: 'string' as const,
 			nullable: false as const, optional: true as const,
@@ -396,10 +430,63 @@ export const packedUserSchema = {
 			nullable: true as const, optional: true as const,
 			format: 'date-time',
 		},
+		bannerUrl: {
+			type: 'string' as const,
+			format: 'url',
+			nullable: true as const, optional: true as const,
+		},
+		bannerBlurhash: {
+			type: 'any' as const,
+			nullable: true as const, optional: true as const,
+		},
+		bannerColor: {
+			type: 'any' as const,
+			nullable: true as const, optional: true as const,
+			default: null
+		},
+		isLocked: {
+			type: 'boolean' as const,
+			nullable: false as const, optional: true as const,
+		},
+		isSuspended: {
+			type: 'boolean' as const,
+			nullable: false as const, optional: false as const,
+			example: false
+		},
+		description: {
+			type: 'string' as const,
+			nullable: true as const, optional: true as const,
+			description: 'The user-defined UTF-8 string describing their account.',
+			example: 'Hi masters, I am Ai!'
+		},
 		location: {
 			type: 'string' as const,
 			nullable: true as const, optional: true as const,
 		},
+		birthday: {
+			type: 'string' as const,
+			nullable: true as const, optional: true as const,
+			example: '2018-03-12'
+		},
+		fields: {
+			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,
+				properties: {
+					name: {
+						type: 'string' as const,
+						nullable: false as const, optional: false as const
+					},
+					value: {
+						type: 'string' as const,
+						nullable: false as const, optional: false as const
+					}
+				},
+				maxLength: 4
+			}
+		},
 		followersCount: {
 			type: 'number' as const,
 			nullable: false as const, optional: true as const,
@@ -415,11 +502,6 @@ export const packedUserSchema = {
 			nullable: false as const, optional: true as const,
 			description: 'The number of Notes (including renotes) issued by the user.'
 		},
-		isBot: {
-			type: 'boolean' as const,
-			nullable: false as const, optional: true as const,
-			description: 'Whether this account is a bot.'
-		},
 		pinnedNoteIds: {
 			type: 'array' as const,
 			nullable: false as const, optional: true as const,
@@ -438,24 +520,59 @@ export const packedUserSchema = {
 				ref: 'Note'
 			}
 		},
-		isCat: {
-			type: 'boolean' as const,
-			nullable: false as const, optional: true as const,
-			description: 'Whether this account is a cat.'
+		pinnedPageId: {
+			type: 'string' as const,
+			nullable: true as const, optional: false as const
 		},
-		isAdmin: {
-			type: 'boolean' as const,
-			nullable: false as const, optional: true as const,
-			description: 'Whether this account is the admin.'
+		pinnedPage: {
+			type: 'object' as const,
+			nullable: true as const, optional: false as const,
+			ref: 'Page'
 		},
-		isModerator: {
+		twoFactorEnabled: {
 			type: 'boolean' as const,
-			nullable: false as const, optional: true as const,
-			description: 'Whether this account is a moderator.'
+			nullable: false as const, optional: false as const,
+			default: false
 		},
-		isLocked: {
+		usePasswordLessLogin: {
 			type: 'boolean' as const,
-			nullable: false as const, optional: true as const,
+			nullable: false as const, optional: false as const,
+			default: false
+		},
+		securityKeys: {
+			type: 'boolean' as const,
+			nullable: false as const, optional: false as const,
+			default: false
+		},
+		avatarId: {
+			type: 'string' as const,
+			nullable: true as const, optional: true as const,
+			format: 'id'
+		},
+		bannerId: {
+			type: 'string' as const,
+			nullable: true as const, optional: true as const,
+			format: 'id'
+		},
+		autoWatch: {
+			type: 'boolean' as const,
+			nullable: false as const, optional: true as const
+		},
+		injectFeaturedNote: {
+			type: 'boolean' as const,
+			nullable: false as const, optional: true as const
+		},
+		alwaysMarkNsfw: {
+			type: 'boolean' as const,
+			nullable: false as const, optional: true as const
+		},
+		carefulBot: {
+			type: 'boolean' as const,
+			nullable: false as const, optional: true as const
+		},
+		autoAcceptFollowed: {
+			type: 'boolean' as const,
+			nullable: false as const, optional: true as const
 		},
 		hasUnreadSpecifiedNotes: {
 			type: 'boolean' as const,
@@ -465,5 +582,69 @@ export const packedUserSchema = {
 			type: 'boolean' as const,
 			nullable: false as const, optional: true as const,
 		},
+		hasUnreadAnnouncement: {
+			type: 'boolean' as const,
+			nullable: false as const, optional: true as const,
+		},
+		hasUnreadAntenna: {
+			type: 'boolean' as const,
+			nullable: false as const, optional: true as const,
+		},
+		hasUnreadChannel: {
+			type: 'boolean' as const,
+			nullable: false as const, optional: true as const,
+		},
+		hasUnreadMessagingMessage: {
+			type: 'boolean' as const,
+			nullable: false as const, optional: true as const,
+		},
+		hasUnreadNotification: {
+			type: 'boolean' as const,
+			nullable: false as const, optional: true as const,
+		},
+		hasPendingReceivedFollowRequest: {
+			type: 'boolean' as const,
+			nullable: false as const, optional: true as const,
+		},
+		integrations: {
+			type: 'object' as const,
+			nullable: false as const, optional: true as const
+		},
+		mutedWords: {
+			type: 'array' as const,
+			nullable: false as const, optional: true as const
+		},
+		mutingNotificationTypes: {
+			type: 'array' as const,
+			nullable: false as const, optional: true as const
+		},
+		isFollowing: {
+			type: 'boolean' as const,
+			optional: true as const, nullable: false as const
+		},
+		hasPendingFollowRequestFromYou: {
+			type: 'boolean' as const,
+			optional: true as const, nullable: false as const
+		},
+		hasPendingFollowRequestToYou: {
+			type: 'boolean' as const,
+			optional: true as const, nullable: false as const
+		},
+		isFollowed: {
+			type: 'boolean' as const,
+			optional: true as const, nullable: false as const
+		},
+		isBlocking: {
+			type: 'boolean' as const,
+			optional: true as const, nullable: false as const
+		},
+		isBlocked: {
+			type: 'boolean' as const,
+			optional: true as const, nullable: false as const
+		},
+		isMuted: {
+			type: 'boolean' as const,
+			optional: true as const, nullable: false as const
+		}
 	},
 };