From 484e023c0c8ad348438edfeee73623223e6ad088 Mon Sep 17 00:00:00 2001 From: Johann150 Date: Sat, 2 Apr 2022 08:04:36 +0200 Subject: enhance(doc): required input fields (#8456) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 --- .../src/server/api/endpoints/admin/drive/files.ts | 7 ++++++- .../server/api/endpoints/admin/drive/show-file.ts | 20 +++++++++++++++----- .../server/api/endpoints/admin/emoji/list-remote.ts | 8 +++++++- .../src/server/api/endpoints/admin/emoji/list.ts | 5 +++-- .../api/endpoints/admin/emoji/set-category-bulk.ts | 6 +++++- .../src/server/api/endpoints/admin/emoji/update.ts | 6 +++++- .../src/server/api/endpoints/admin/show-users.ts | 9 +++++++-- 7 files changed, 48 insertions(+), 13 deletions(-) (limited to 'packages/backend/src/server/api/endpoints/admin') diff --git a/packages/backend/src/server/api/endpoints/admin/drive/files.ts b/packages/backend/src/server/api/endpoints/admin/drive/files.ts index 646d85a1e0..119c4db19b 100644 --- a/packages/backend/src/server/api/endpoints/admin/drive/files.ts +++ b/packages/backend/src/server/api/endpoints/admin/drive/files.ts @@ -27,7 +27,12 @@ export const paramDef = { untilId: { type: 'string', format: 'misskey:id' }, type: { type: 'string', nullable: true, pattern: /^[a-zA-Z0-9\/\-*]+$/.toString().slice(1, -1) }, origin: { type: 'string', enum: ['combined', 'local', 'remote'], default: "local" }, - hostname: { type: 'string', nullable: true, default: null }, + hostname: { + type: 'string', + nullable: true, + default: null, + description: 'The local host is represented with `null`.', + }, }, required: [], } as const; diff --git a/packages/backend/src/server/api/endpoints/admin/drive/show-file.ts b/packages/backend/src/server/api/endpoints/admin/drive/show-file.ts index 4b27fc0188..039df74f1b 100644 --- a/packages/backend/src/server/api/endpoints/admin/drive/show-file.ts +++ b/packages/backend/src/server/api/endpoints/admin/drive/show-file.ts @@ -40,6 +40,7 @@ export const meta = { userHost: { type: 'string', optional: false, nullable: true, + description: 'The local host is represented with `null`.', }, md5: { type: 'string', @@ -151,11 +152,20 @@ export const meta = { export const paramDef = { type: 'object', - properties: { - fileId: { type: 'string', format: 'misskey:id' }, - url: { type: 'string' }, - }, - required: [], + anyOf: [ + { + properties: { + fileId: { type: 'string', format: 'misskey:id' }, + }, + required: ['fileId'], + }, + { + properties: { + url: { type: 'string' }, + }, + required: ['url'], + }, + ], } as const; // eslint-disable-next-line import/no-default-export diff --git a/packages/backend/src/server/api/endpoints/admin/emoji/list-remote.ts b/packages/backend/src/server/api/endpoints/admin/emoji/list-remote.ts index f19c3ddbd8..d16689a280 100644 --- a/packages/backend/src/server/api/endpoints/admin/emoji/list-remote.ts +++ b/packages/backend/src/server/api/endpoints/admin/emoji/list-remote.ts @@ -40,6 +40,7 @@ export const meta = { host: { type: 'string', optional: false, nullable: true, + description: 'The local host is represented with `null`.', }, url: { type: 'string', @@ -54,7 +55,12 @@ export const paramDef = { type: 'object', properties: { query: { type: 'string', nullable: true, default: null }, - host: { type: 'string', nullable: true, default: null }, + host: { + type: 'string', + nullable: true, + default: null, + description: 'Use `null` to represent the local host.', + }, 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/admin/emoji/list.ts b/packages/backend/src/server/api/endpoints/admin/emoji/list.ts index f488a71a00..6192978fad 100644 --- a/packages/backend/src/server/api/endpoints/admin/emoji/list.ts +++ b/packages/backend/src/server/api/endpoints/admin/emoji/list.ts @@ -38,8 +38,9 @@ export const meta = { optional: false, nullable: true, }, host: { - type: 'string', - optional: false, nullable: true, + type: 'null', + optional: false, + description: 'The local host is represented with `null`. The field exists for compatibility with other API endpoints that return files.', }, url: { type: 'string', diff --git a/packages/backend/src/server/api/endpoints/admin/emoji/set-category-bulk.ts b/packages/backend/src/server/api/endpoints/admin/emoji/set-category-bulk.ts index 6063f3e3be..cff58d6170 100644 --- a/packages/backend/src/server/api/endpoints/admin/emoji/set-category-bulk.ts +++ b/packages/backend/src/server/api/endpoints/admin/emoji/set-category-bulk.ts @@ -17,7 +17,11 @@ export const paramDef = { ids: { type: 'array', items: { type: 'string', format: 'misskey:id', } }, - category: { type: 'string', nullable: true }, + category: { + type: 'string', + nullable: true, + description: 'Use `null` to reset the category.', + }, }, required: ['ids'], } as const; diff --git a/packages/backend/src/server/api/endpoints/admin/emoji/update.ts b/packages/backend/src/server/api/endpoints/admin/emoji/update.ts index e26514e0ca..5b547b3b79 100644 --- a/packages/backend/src/server/api/endpoints/admin/emoji/update.ts +++ b/packages/backend/src/server/api/endpoints/admin/emoji/update.ts @@ -23,7 +23,11 @@ export const paramDef = { properties: { id: { type: 'string', format: 'misskey:id' }, name: { type: 'string' }, - category: { type: 'string', nullable: true }, + category: { + type: 'string', + nullable: true, + description: 'Use `null` to reset the category.', + }, aliases: { type: 'array', items: { type: 'string', } }, diff --git a/packages/backend/src/server/api/endpoints/admin/show-users.ts b/packages/backend/src/server/api/endpoints/admin/show-users.ts index 1ec86fef2e..2703b4b9db 100644 --- a/packages/backend/src/server/api/endpoints/admin/show-users.ts +++ b/packages/backend/src/server/api/endpoints/admin/show-users.ts @@ -26,8 +26,13 @@ export const paramDef = { sort: { type: 'string', enum: ['+follower', '-follower', '+createdAt', '-createdAt', '+updatedAt', '-updatedAt'] }, state: { type: 'string', enum: ['all', 'available', 'admin', 'moderator', 'adminOrModerator', 'silenced', 'suspended'], default: "all" }, origin: { type: 'string', enum: ['combined', 'local', 'remote'], default: "local" }, - username: { type: 'string', default: null }, - hostname: { type: 'string', default: null }, + username: { type: 'string', nullable: true, default: null }, + hostname: { + type: 'string', + nullable: true, + default: null, + description: 'The local host is represented with `null`.', + }, }, required: [], } as const; -- cgit v1.2.3-freya