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>

4 files changed, 69 insertions, 18 deletions

diff --git a/packages/backend/src/server/api/endpoints/users/followers.ts b/packages/backend/src/server/api/endpoints/users/followers.ts
index 5de624312a..26b1f20df0 100644
--- a/packages/backend/src/server/api/endpoints/users/followers.ts
+++ b/packages/backend/src/server/api/endpoints/users/followers.ts
@@ -38,14 +38,29 @@ export const meta = {
 export const paramDef = {
 	type: 'object',
 	properties: {
-		userId: { type: 'string', format: 'misskey:id' },
-		username: { type: 'string' },
-		host: { type: 'string', nullable: true },
 		sinceId: { type: 'string', format: 'misskey:id' },
 		untilId: { type: 'string', format: 'misskey:id' },
 		limit: { type: 'integer', minimum: 1, maximum: 100, default: 10 },
 	},
-	required: [],
+	anyOf: [
+		{
+			properties: {
+				userId: { type: 'string', format: 'misskey:id' },
+			},
+			required: ['userId'],
+		},
+		{
+			properties: {
+				username: { type: 'string' },
+				host: {
+					type: 'string',
+					nullable: true,
+					description: 'The local host is represented with `null`.',
+				},
+			},
+			required: ['username', 'host'],
+		},
+	],
 } as const;
 
 // eslint-disable-next-line import/no-default-export
diff --git a/packages/backend/src/server/api/endpoints/users/following.ts b/packages/backend/src/server/api/endpoints/users/following.ts
index 55460f7c67..42cf5216e8 100644
--- a/packages/backend/src/server/api/endpoints/users/following.ts
+++ b/packages/backend/src/server/api/endpoints/users/following.ts
@@ -38,14 +38,29 @@ export const meta = {
 export const paramDef = {
 	type: 'object',
 	properties: {
-		userId: { type: 'string', format: 'misskey:id' },
-		username: { type: 'string' },
-		host: { type: 'string', nullable: true },
 		sinceId: { type: 'string', format: 'misskey:id' },
 		untilId: { type: 'string', format: 'misskey:id' },
 		limit: { type: 'integer', minimum: 1, maximum: 100, default: 10 },
 	},
-	required: [],
+	anyOf: [
+		{
+			properties: {
+				userId: { type: 'string', format: 'misskey:id' },
+			},
+			required: ['userId'],
+		},
+		{
+			properties: {
+				username: { type: 'string' },
+				host: {
+					type: 'string',
+					nullable: true,
+					description: 'The local host is represented with `null`.',
+				},
+			},
+			required: ['username', 'host'],
+		},
+	],
 } as const;
 
 // eslint-disable-next-line import/no-default-export
diff --git a/packages/backend/src/server/api/endpoints/users/search-by-username-and-host.ts b/packages/backend/src/server/api/endpoints/users/search-by-username-and-host.ts
index 897b5de3fe..f74d80e2ae 100644
--- a/packages/backend/src/server/api/endpoints/users/search-by-username-and-host.ts
+++ b/packages/backend/src/server/api/endpoints/users/search-by-username-and-host.ts
@@ -28,7 +28,10 @@ export const paramDef = {
 		limit: { type: 'integer', minimum: 1, maximum: 100, default: 10 },
 		detail: { type: 'boolean', default: true },
 	},
-	required: [],
+	anyOf: [
+		{ required: ['username'] },
+		{ required: ['host'] },
+	],
 } as const;
 
 // TODO: avatar,bannerをJOINしたいけどエラーになる
diff --git a/packages/backend/src/server/api/endpoints/users/show.ts b/packages/backend/src/server/api/endpoints/users/show.ts
index 775a4b29ff..b1a568145a 100644
--- a/packages/backend/src/server/api/endpoints/users/show.ts
+++ b/packages/backend/src/server/api/endpoints/users/show.ts
@@ -46,15 +46,33 @@ export const meta = {
 
 export const paramDef = {
 	type: 'object',
-	properties: {
-		userId: { type: 'string', format: 'misskey:id' },
-		userIds: { type: 'array', uniqueItems: true, items: {
-			type: 'string', format: 'misskey:id',
-		} },
-		username: { type: 'string' },
-		host: { type: 'string', nullable: true },
-	},
-	required: [],
+	anyOf: [
+		{
+			properties: {
+				userId: { type: 'string', format: 'misskey:id' },
+			},
+			required: ['userId'],
+		},
+		{
+			properties: {
+				userIds: { type: 'array', uniqueItems: true, items: {
+					type: 'string', format: 'misskey:id',
+				} },
+			},
+			required: ['userIds'],
+		},
+		{
+			properties: {
+				username: { type: 'string' },
+				host: {
+					type: 'string',
+					nullable: true,
+					description: 'The local host is represented with `null`.',
+				},
+			},
+			required: ['username', 'host'],
+		},
+	],
 } as const;
 
 // eslint-disable-next-line import/no-default-export