enhance(doc): required input fields (#8456)

* remove empty file

If the endpoint is to be implemented later, the file can be added back,
but for now it is confusing to have an empty file.

* enhance(doc): document defaults

Default for `isPublic` is based on the database schema default value.
Defaults for `local` and `withFiles` are based on the behaviour of the endpoint.

* enhance(doc): explain nullable emoji category

* fix: make nullable if default is null

* enhance(doc): explain mute attribute expiresAt

* fix: define required fields

- `notes/create`: the default for `text` has been removed because ajv can not handle
  `default` inside of `anyOf`, see
  https://ajv.js.org/guide/modifying-data.html#assigning-defaults
  and the default value cannot be `null` if text is `nullable: false` in the `anyOf`
  first alternative.
- `notes/create`: The `mediaIds` property has been marked as deprecated because it
  has the same behaviour as using `fileIds`, but the implementation tries to handlè
  `fileIds` first.
- The result schema for `admin/emoji/list` has been altered because the `host`
  property will always be `null` as it is filtered this way in the database query.
  See packages/backend/src/server/api/endpoints/admin/emoji/list.ts line 67.

* enhance(doc): explain nullable hostname

* update changelog

Co-authored-by: syuilo <Syuilotan@yahoo.co.jp>

8 files changed, 109 insertions, 38 deletions

diff --git a/packages/backend/src/server/api/endpoints/notes/create.ts b/packages/backend/src/server/api/endpoints/notes/create.ts
index 961983f5f4..4b18ab6023 100644
--- a/packages/backend/src/server/api/endpoints/notes/create.ts
+++ b/packages/backend/src/server/api/endpoints/notes/create.ts
@@ -59,12 +59,6 @@ export const meta = {
 			id: '3ac74a84-8fd5-4bb0-870f-01804f82ce15',
 		},
 
-		contentRequired: {
-			message: 'Content required. You need to set text, fileIds, renoteId or poll.',
-			code: 'CONTENT_REQUIRED',
-			id: '6f57e42b-c348-439b-bc45-993995cc515a',
-		},
-
 		cannotCreateAlreadyExpiredPoll: {
 			message: 'Poll is already expired.',
 			code: 'CANNOT_CREATE_ALREADY_EXPIRED_POLL',
@@ -92,29 +86,41 @@ export const paramDef = {
 		visibleUserIds: { type: 'array', uniqueItems: true, items: {
 			type: 'string', format: 'misskey:id',
 		} },
-		text: { type: 'string', nullable: true, maxLength: MAX_NOTE_TEXT_LENGTH, default: null },
+		text: { type: 'string', maxLength: MAX_NOTE_TEXT_LENGTH, nullable: true },
 		cw: { type: 'string', nullable: true, maxLength: 100 },
 		localOnly: { type: 'boolean', default: false },
 		noExtractMentions: { type: 'boolean', default: false },
 		noExtractHashtags: { type: 'boolean', default: false },
 		noExtractEmojis: { type: 'boolean', default: false },
-		fileIds: { type: 'array', uniqueItems: true, minItems: 1, maxItems: 16, items: {
-			type: 'string', format: 'misskey:id',
-		} },
-		mediaIds: { type: 'array', uniqueItems: true, minItems: 1, maxItems: 16, items: {
-			type: 'string', format: 'misskey:id',
-		} },
+		fileIds: {
+			type: 'array',
+			uniqueItems: true,
+			minItems: 1,
+			maxItems: 16,
+			items: { type: 'string', format: 'misskey:id' },
+		},
+		mediaIds: {
+			deprecated: true,
+			description: 'Use `fileIds` instead. If both are specified, this property is discarded.',
+			type: 'array',
+			uniqueItems: true,
+			minItems: 1,
+			maxItems: 16,
+			items: { type: 'string', format: 'misskey:id' },
+		},
 		replyId: { type: 'string', format: 'misskey:id', nullable: true },
 		renoteId: { type: 'string', format: 'misskey:id', nullable: true },
 		channelId: { type: 'string', format: 'misskey:id', nullable: true },
 		poll: {
-			type: 'object', nullable: true,
+			type: 'object',
+			nullable: true,
 			properties: {
 				choices: {
-					type: 'array', uniqueItems: true, minItems: 2, maxItems: 10, 
-					items: {
-						type: 'string', minLength: 1, maxLength: 50,
-					},
+					type: 'array',
+					uniqueItems: true,
+					minItems: 2,
+					maxItems: 10,
+					items: { type: 'string', minLength: 1, maxLength: 50 },
 				},
 				multiple: { type: 'boolean', default: false },
 				expiresAt: { type: 'integer', nullable: true },
@@ -123,7 +129,30 @@ export const paramDef = {
 			required: ['choices'],
 		},
 	},
-	required: [],
+	anyOf: [
+		{
+			// (re)note with text, files and poll are optional
+			properties: {
+				text: { type: 'string', maxLength: MAX_NOTE_TEXT_LENGTH, nullable: false },
+			},
+			required: ['text'],
+		},
+		{
+			// (re)note with files, text and poll are optional
+			required: ['fileIds'],
+		},
+		{
+			// (re)note with files, text and poll are optional
+			required: ['mediaIds'],
+		},
+		{
+			// (re)note with poll, text and files are optional
+			properties: {
+				poll: { type: 'object', nullable: false, },
+			},
+			required: ['poll'],
+		},
+	],
 } as const;
 
 // eslint-disable-next-line import/no-default-export
@@ -204,11 +233,6 @@ export default define(meta, paramDef, async (ps, user) => {
 		}
 	}
 
-	// テキストが無いかつ添付ファイルが無いかつRenoteも無いかつ投票も無かったらエラー
-	if (!(ps.text || files.length || renote || ps.poll)) {
-		throw new ApiError(meta.errors.contentRequired);
-	}
-
 	let channel: Channel | undefined;
 	if (ps.channelId != null) {
 		channel = await Channels.findOneBy({ id: ps.channelId });
diff --git a/packages/backend/src/server/api/endpoints/notes/global-timeline.ts b/packages/backend/src/server/api/endpoints/notes/global-timeline.ts
index 09a8194665..cb402ecaa1 100644
--- a/packages/backend/src/server/api/endpoints/notes/global-timeline.ts
+++ b/packages/backend/src/server/api/endpoints/notes/global-timeline.ts
@@ -35,7 +35,11 @@ export const meta = {
 export const paramDef = {
 	type: 'object',
 	properties: {
-		withFiles: { type: 'boolean' },
+		withFiles: {
+			type: 'boolean',
+			default: false,
+			description: 'Only show notes that have attached files.',
+		},
 		limit: { type: 'integer', minimum: 1, maximum: 100, default: 10 },
 		sinceId: { type: 'string', format: 'misskey:id' },
 		untilId: { type: 'string', format: 'misskey:id' },
diff --git a/packages/backend/src/server/api/endpoints/notes/hybrid-timeline.ts b/packages/backend/src/server/api/endpoints/notes/hybrid-timeline.ts
index 7c9c122963..f9893527e0 100644
--- a/packages/backend/src/server/api/endpoints/notes/hybrid-timeline.ts
+++ b/packages/backend/src/server/api/endpoints/notes/hybrid-timeline.ts
@@ -48,7 +48,11 @@ export const paramDef = {
 		includeMyRenotes: { type: 'boolean', default: true },
 		includeRenotedMyNotes: { type: 'boolean', default: true },
 		includeLocalRenotes: { type: 'boolean', default: true },
-		withFiles: { type: 'boolean' },
+		withFiles: {
+			type: 'boolean',
+			default: false,
+			description: 'Only show notes that have attached files.',
+		},
 	},
 	required: [],
 } as const;
diff --git a/packages/backend/src/server/api/endpoints/notes/local-timeline.ts b/packages/backend/src/server/api/endpoints/notes/local-timeline.ts
index bb0bbe2a20..03edf30b31 100644
--- a/packages/backend/src/server/api/endpoints/notes/local-timeline.ts
+++ b/packages/backend/src/server/api/endpoints/notes/local-timeline.ts
@@ -37,7 +37,11 @@ export const meta = {
 export const paramDef = {
 	type: 'object',
 	properties: {
-		withFiles: { type: 'boolean' },
+		withFiles: {
+			type: 'boolean',
+			default: false,
+			description: 'Only show notes that have attached files.',
+		},
 		fileType: { type: 'array', items: {
 			type: 'string',
 		} },
diff --git a/packages/backend/src/server/api/endpoints/notes/search-by-tag.ts b/packages/backend/src/server/api/endpoints/notes/search-by-tag.ts
index c6503eb057..bb85c92008 100644
--- a/packages/backend/src/server/api/endpoints/notes/search-by-tag.ts
+++ b/packages/backend/src/server/api/endpoints/notes/search-by-tag.ts
@@ -25,21 +25,44 @@ export const meta = {
 export const paramDef = {
 	type: 'object',
 	properties: {
-		tag: { type: 'string' },
-		query: { type: 'array', items: {
-			type: 'array', items: {
-				type: 'string',
-			},
-		} },
 		reply: { type: 'boolean', nullable: true, default: null },
 		renote: { type: 'boolean', nullable: true, default: null },
-		withFiles: { type: 'boolean' },
+		withFiles: {
+			type: 'boolean',
+			default: false,
+			description: 'Only show notes that have attached files.',
+		},
 		poll: { type: 'boolean', nullable: true, default: null },
 		sinceId: { type: 'string', format: 'misskey:id' },
 		untilId: { type: 'string', format: 'misskey:id' },
 		limit: { type: 'integer', minimum: 1, maximum: 100, default: 10 },
 	},
-	required: [],
+	anyOf: [
+		{
+			properties: {
+				tag: { type: 'string', minLength: 1 },
+			},
+			required: ['tag'],
+		},
+		{
+			properties: {
+				query: {
+					type: 'array',
+					description: 'The outer arrays are chained with OR, the inner arrays are chained with AND.',
+					items: {
+						type: 'array',
+						items: {
+							type: 'string',
+							minLength: 1,
+						},
+						minItems: 1,
+					},
+					minItems: 1,
+				},
+			},
+			required: ['query'],
+		},
+	],
 } as const;
 
 // eslint-disable-next-line import/no-default-export
diff --git a/packages/backend/src/server/api/endpoints/notes/search.ts b/packages/backend/src/server/api/endpoints/notes/search.ts
index e77892b150..af9b5f0a10 100644
--- a/packages/backend/src/server/api/endpoints/notes/search.ts
+++ b/packages/backend/src/server/api/endpoints/notes/search.ts
@@ -35,7 +35,11 @@ export const paramDef = {
 		untilId: { type: 'string', format: 'misskey:id' },
 		limit: { type: 'integer', minimum: 1, maximum: 100, default: 10 },
 		offset: { type: 'integer', default: 0 },
-		host: { type: 'string', nullable: true },
+		host: {
+			type: 'string',
+			nullable: true,
+			description: 'The local host is represented with `null`.',
+		},
 		userId: { type: 'string', format: 'misskey:id', nullable: true, default: null },
 		channelId: { type: 'string', format: 'misskey:id', nullable: true, default: null },
 	},
diff --git a/packages/backend/src/server/api/endpoints/notes/timeline.ts b/packages/backend/src/server/api/endpoints/notes/timeline.ts
index fde66b241b..0f976d18be 100644
--- a/packages/backend/src/server/api/endpoints/notes/timeline.ts
+++ b/packages/backend/src/server/api/endpoints/notes/timeline.ts
@@ -38,7 +38,11 @@ export const paramDef = {
 		includeMyRenotes: { type: 'boolean', default: true },
 		includeRenotedMyNotes: { type: 'boolean', default: true },
 		includeLocalRenotes: { type: 'boolean', default: true },
-		withFiles: { type: 'boolean' },
+		withFiles: {
+			type: 'boolean',
+			default: false,
+			description: 'Only show notes that have attached files.',
+		},
 	},
 	required: [],
 } as const;
diff --git a/packages/backend/src/server/api/endpoints/notes/user-list-timeline.ts b/packages/backend/src/server/api/endpoints/notes/user-list-timeline.ts
index 866e306d8d..6c6402603a 100644
--- a/packages/backend/src/server/api/endpoints/notes/user-list-timeline.ts
+++ b/packages/backend/src/server/api/endpoints/notes/user-list-timeline.ts
@@ -42,7 +42,11 @@ export const paramDef = {
 		includeMyRenotes: { type: 'boolean', default: true },
 		includeRenotedMyNotes: { type: 'boolean', default: true },
 		includeLocalRenotes: { type: 'boolean', default: true },
-		withFiles: { type: 'boolean' },
+		withFiles: {
+			type: 'boolean',
+			default: false,
+			description: 'Only show notes that have attached files.',
+		},
 	},
 	required: ['listId'],
 } as const;