From a07d753da84191bc8c185a7bcd6d73fab9529b5d Mon Sep 17 00:00:00 2001 From: YuzuRyo61 Date: Sat, 6 Mar 2021 22:34:11 +0900 Subject: APIドキュメントの改善 (#6757) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 --- .../api/endpoints/admin/announcements/create.ts | 46 ++++++++++++++++++ .../api/endpoints/admin/announcements/delete.ts | 5 ++ .../api/endpoints/admin/announcements/list.ts | 55 ++++++++++++++++++++++ .../api/endpoints/admin/announcements/update.ts | 5 ++ 4 files changed, 111 insertions(+) (limited to 'src/server/api/endpoints/admin/announcements') diff --git a/src/server/api/endpoints/admin/announcements/create.ts b/src/server/api/endpoints/admin/announcements/create.ts index f9fb30f49f..dc01621c75 100644 --- a/src/server/api/endpoints/admin/announcements/create.ts +++ b/src/server/api/endpoints/admin/announcements/create.ts @@ -4,6 +4,11 @@ import { Announcements } from '../../../../../models'; import { genId } from '../../../../../misc/gen-id'; export const meta = { + desc: { + 'ja-JP': 'アナウンスを作成します。', + 'en-US': 'Create a announcement.' + }, + tags: ['admin'], requireCredential: true as const, @@ -19,6 +24,47 @@ export const meta = { imageUrl: { validator: $.nullable.str.min(1) } + }, + + res: { + 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', + description: 'The unique identifier for this Announcement.', + example: 'xxxxxxxxxx', + }, + createdAt: { + type: 'string' as const, + optional: false as const, nullable: false as const, + format: 'date-time', + description: 'The date that the Announcement was created.' + }, + updatedAt: { + type: 'string' as const, + optional: false as const, nullable: true as const, + format: 'date-time', + description: 'The date that the Announcement was updated.' + }, + title: { + type: 'string' as const, + optional: false as const, nullable: false as const, + description: 'Announcement title.' + }, + text: { + type: 'string' as const, + optional: false as const, nullable: false as const, + description: 'Announcement text.' + }, + imageUrl: { + type: 'string' as const, + optional: false as const, nullable: true as const, + description: 'Announcement image.' + } + } } }; diff --git a/src/server/api/endpoints/admin/announcements/delete.ts b/src/server/api/endpoints/admin/announcements/delete.ts index 1b7a0bf921..6c9c065757 100644 --- a/src/server/api/endpoints/admin/announcements/delete.ts +++ b/src/server/api/endpoints/admin/announcements/delete.ts @@ -10,6 +10,11 @@ export const meta = { requireCredential: true as const, requireModerator: true, + desc: { + 'ja-JP': 'アナウンスを削除します。', + 'en-US': 'Delete a announcement.' + }, + params: { id: { validator: $.type(ID) diff --git a/src/server/api/endpoints/admin/announcements/list.ts b/src/server/api/endpoints/admin/announcements/list.ts index 4c3af5a318..5489b0d2c7 100644 --- a/src/server/api/endpoints/admin/announcements/list.ts +++ b/src/server/api/endpoints/admin/announcements/list.ts @@ -5,6 +5,11 @@ import { Announcements, AnnouncementReads } from '../../../../../models'; import { makePaginationQuery } from '../../../common/make-pagination-query'; export const meta = { + desc: { + 'ja-JP': 'アナウンスのリストを表示します。', + 'en-US': 'List announcements.' + }, + tags: ['admin'], requireCredential: true as const, @@ -23,6 +28,56 @@ export const meta = { untilId: { validator: $.optional.type(ID), }, + }, + + 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', + description: 'The unique identifier for this Announcement.', + example: 'xxxxxxxxxx', + }, + createdAt: { + type: 'string' as const, + optional: false as const, nullable: false as const, + format: 'date-time', + description: 'The date that the Announcement was created.' + }, + updatedAt: { + type: 'string' as const, + optional: false as const, nullable: true as const, + format: 'date-time', + description: 'The date that the Announcement was updated.' + }, + text: { + type: 'string' as const, + optional: false as const, nullable: false as const, + description: 'Announcement text.' + }, + title: { + type: 'string' as const, + optional: false as const, nullable: false as const, + description: 'Announcement title.' + }, + imageUrl: { + type: 'string' as const, + optional: false as const, nullable: true as const, + description: 'Announcement image.' + }, + reads: { + type: 'number' as const, + optional: false as const, nullable: false as const, + description: 'Number of people who read this announcement.' + } + } + } } }; diff --git a/src/server/api/endpoints/admin/announcements/update.ts b/src/server/api/endpoints/admin/announcements/update.ts index fd24f8cc8e..9c4165eae0 100644 --- a/src/server/api/endpoints/admin/announcements/update.ts +++ b/src/server/api/endpoints/admin/announcements/update.ts @@ -5,6 +5,11 @@ import { Announcements } from '../../../../../models'; import { ApiError } from '../../../error'; export const meta = { + desc: { + 'ja-JP': 'アナウンスの内容を変更します。', + 'en-US': 'Update a annoucement.' + }, + tags: ['admin'], requireCredential: true as const, -- cgit v1.2.3-freya