From 60c9a6528f10ab63ca03fd1012a63c08727492fb Mon Sep 17 00:00:00 2001 From: syuilo Date: Mon, 25 Feb 2019 04:18:09 +0900 Subject: [PATCH] Improve doc --- src/server/api/endpoints.ts | 1 + .../api/endpoints/auth/session/generate.ts | 14 +++++++++++ .../api/endpoints/auth/session/userkey.ts | 15 ++++++++++++ src/server/api/endpoints/notes.ts | 1 + src/server/api/endpoints/notes/create.ts | 1 + .../api/endpoints/notes/global-timeline.ts | 1 + .../api/endpoints/notes/hybrid-timeline.ts | 1 + .../api/endpoints/notes/local-timeline.ts | 1 + .../api/endpoints/notes/search-by-tag.ts | 1 + src/server/api/endpoints/notes/timeline.ts | 1 + .../api/endpoints/notes/user-list-timeline.ts | 1 + src/server/api/endpoints/users/notes.ts | 1 + src/server/api/openapi/description.ts | 23 +++++++++---------- src/server/api/openapi/gen-spec.ts | 2 ++ 14 files changed, 52 insertions(+), 12 deletions(-) diff --git a/src/server/api/endpoints.ts b/src/server/api/endpoints.ts index 13bf2538db..1a8fca6dfa 100644 --- a/src/server/api/endpoints.ts +++ b/src/server/api/endpoints.ts @@ -7,6 +7,7 @@ export type Param = { validator: Context; transform?: any; default?: any; + deprecated?: boolean; desc?: { [key: string]: string }; ref?: string; }; diff --git a/src/server/api/endpoints/auth/session/generate.ts b/src/server/api/endpoints/auth/session/generate.ts index ddbd7209c9..e12bea7681 100644 --- a/src/server/api/endpoints/auth/session/generate.ts +++ b/src/server/api/endpoints/auth/session/generate.ts @@ -21,6 +21,20 @@ export const meta = { } }, + res: { + type: 'object', + properties: { + token: { + type: 'string', + description: 'セッションのトークン' + }, + url: { + type: 'string', + description: 'セッションのURL' + }, + } + }, + errors: { noSuchApp: { message: 'No such app.', diff --git a/src/server/api/endpoints/auth/session/userkey.ts b/src/server/api/endpoints/auth/session/userkey.ts index 49dde23ede..e09e16e658 100644 --- a/src/server/api/endpoints/auth/session/userkey.ts +++ b/src/server/api/endpoints/auth/session/userkey.ts @@ -29,6 +29,21 @@ export const meta = { } }, + res: { + type: 'object', + properties: { + accessToken: { + type: 'string', + description: 'ユーザーのアクセストークン', + }, + + user: { + type: 'User', + description: '認証したユーザー' + }, + } + }, + errors: { noSuchApp: { message: 'No such app.', diff --git a/src/server/api/endpoints/notes.ts b/src/server/api/endpoints/notes.ts index 8283e92bfe..835c515cfe 100644 --- a/src/server/api/endpoints/notes.ts +++ b/src/server/api/endpoints/notes.ts @@ -41,6 +41,7 @@ export const meta = { media: { validator: $.optional.bool, + deprecated: true, desc: { 'ja-JP': 'ファイルが添付された投稿に限定するか否か (このパラメータは廃止予定です。代わりに withFiles を使ってください。)' } diff --git a/src/server/api/endpoints/notes/create.ts b/src/server/api/endpoints/notes/create.ts index 7df86625d6..bb0d8f94f5 100644 --- a/src/server/api/endpoints/notes/create.ts +++ b/src/server/api/endpoints/notes/create.ts @@ -138,6 +138,7 @@ export const meta = { mediaIds: { validator: $.optional.arr($.type(ID)).unique().range(1, 4), transform: transformMany, + deprecated: true, desc: { 'ja-JP': '添付するファイル (このパラメータは廃止予定です。代わりに fileIds を使ってください。)' } diff --git a/src/server/api/endpoints/notes/global-timeline.ts b/src/server/api/endpoints/notes/global-timeline.ts index b62d8e25a3..0eb761cdb6 100644 --- a/src/server/api/endpoints/notes/global-timeline.ts +++ b/src/server/api/endpoints/notes/global-timeline.ts @@ -24,6 +24,7 @@ export const meta = { mediaOnly: { validator: $.optional.bool, + deprecated: true, desc: { 'ja-JP': 'ファイルが添付された投稿に限定するか否か (このパラメータは廃止予定です。代わりに withFiles を使ってください。)' } diff --git a/src/server/api/endpoints/notes/hybrid-timeline.ts b/src/server/api/endpoints/notes/hybrid-timeline.ts index 153436b9bb..9695547f04 100644 --- a/src/server/api/endpoints/notes/hybrid-timeline.ts +++ b/src/server/api/endpoints/notes/hybrid-timeline.ts @@ -88,6 +88,7 @@ export const meta = { mediaOnly: { validator: $.optional.bool, + deprecated: true, desc: { 'ja-JP': 'true にすると、ファイルが添付された投稿だけ取得します (このパラメータは廃止予定です。代わりに withFiles を使ってください。)' } diff --git a/src/server/api/endpoints/notes/local-timeline.ts b/src/server/api/endpoints/notes/local-timeline.ts index 06c6d7a533..57ef4c3e15 100644 --- a/src/server/api/endpoints/notes/local-timeline.ts +++ b/src/server/api/endpoints/notes/local-timeline.ts @@ -25,6 +25,7 @@ export const meta = { mediaOnly: { validator: $.optional.bool, + deprecated: true, desc: { 'ja-JP': 'ファイルが添付された投稿に限定するか否か (このパラメータは廃止予定です。代わりに withFiles を使ってください。)' } diff --git a/src/server/api/endpoints/notes/search-by-tag.ts b/src/server/api/endpoints/notes/search-by-tag.ts index 0030e2e37a..b33c884049 100644 --- a/src/server/api/endpoints/notes/search-by-tag.ts +++ b/src/server/api/endpoints/notes/search-by-tag.ts @@ -64,6 +64,7 @@ export const meta = { media: { validator: $.optional.nullable.bool, default: null as any, + deprecated: true, desc: { 'ja-JP': 'ファイルが添付された投稿に限定するか否か (このパラメータは廃止予定です。代わりに withFiles を使ってください。)' } diff --git a/src/server/api/endpoints/notes/timeline.ts b/src/server/api/endpoints/notes/timeline.ts index 9ec8070f71..6ff7690c74 100644 --- a/src/server/api/endpoints/notes/timeline.ts +++ b/src/server/api/endpoints/notes/timeline.ts @@ -89,6 +89,7 @@ export const meta = { mediaOnly: { validator: $.optional.bool, + deprecated: true, desc: { 'ja-JP': 'true にすると、ファイルが添付された投稿だけ取得します (このパラメータは廃止予定です。代わりに withFiles を使ってください。)' } diff --git a/src/server/api/endpoints/notes/user-list-timeline.ts b/src/server/api/endpoints/notes/user-list-timeline.ts index 45e96fbdac..17c24ab119 100644 --- a/src/server/api/endpoints/notes/user-list-timeline.ts +++ b/src/server/api/endpoints/notes/user-list-timeline.ts @@ -98,6 +98,7 @@ export const meta = { mediaOnly: { validator: $.optional.bool, + deprecated: true, desc: { 'ja-JP': 'true にすると、ファイルが添付された投稿だけ取得します (このパラメータは廃止予定です。代わりに withFiles を使ってください。)' } diff --git a/src/server/api/endpoints/users/notes.ts b/src/server/api/endpoints/users/notes.ts index f8942fb2d3..10d2f37fc2 100644 --- a/src/server/api/endpoints/users/notes.ts +++ b/src/server/api/endpoints/users/notes.ts @@ -105,6 +105,7 @@ export const meta = { mediaOnly: { validator: $.optional.bool, default: false, + deprecated: true, desc: { 'ja-JP': 'true にすると、ファイルが添付された投稿だけ取得します (このパラメータは廃止予定です。代わりに withFiles を使ってください。)' } diff --git a/src/server/api/openapi/description.ts b/src/server/api/openapi/description.ts index cc5f233c53..04a0b4c719 100644 --- a/src/server/api/openapi/description.ts +++ b/src/server/api/openapi/description.ts @@ -3,16 +3,16 @@ import config from '../../../config'; export const description = ` ## Usage **APIはすべてPOSTでリクエスト/レスポンスともにJSON形式です。** -一部のAPIは認証情報(アクセストークン)が必要です。リクエストの際に\`i\`というパラメータでアクセストークンを添付してください。 +一部のAPIはリクエストに認証情報(APIキー)が必要です。リクエストの際に\`i\`というパラメータでAPIキーを添付してください。 -### 自分のアカウントのアクセストークンを取得する -「設定 > API」で、自分のアクセストークンを取得できます。 +### 自分のアカウントのAPIキーを取得する +「設定 > API」で、自分のAPIキーを取得できます。 > アカウントを不正利用される可能性があるため、このトークンは第三者に教えないでください(アプリなどにも入力しないでください)。 -### アプリケーションとしてアクセストークンを取得する -直接ユーザーのアクセストークンをアプリケーションが扱うのはセキュリティ上のリスクがあるので、 -アプリケーションからAPIを利用する際には、アプリケーションとアプリケーションを利用するユーザーが結び付けられた専用のアクセストークンをMisskeyに発行してもらいます。 +### アプリケーションとしてAPIキーを取得する +直接ユーザーのAPIキーをアプリケーションが扱うのはセキュリティ上のリスクがあるので、 +アプリケーションからAPIを利用する際には、アプリケーションとアプリケーションを利用するユーザーが結び付けられた専用のAPIキーを発行します。 #### 1.アプリケーションを登録する まず、あなたのアプリケーションやWebサービス(以後、あなたのアプリと呼びます)をMisskeyに登録します。 @@ -25,8 +25,7 @@ export const description = ` #### 2.ユーザーに認証させる アプリを使ってもらうには、ユーザーにアカウントへのアクセスの許可をもらう必要があります。 -認証セッションを開始するには、[${config.apiUrl}/auth/session/generate](#operation/auth/session/generate) へパラメータに appSecret としてシークレットキーを含めたリクエストを送信します。 -リクエスト形式はJSONで、メソッドはPOSTです。 +認証セッションを開始するには、[${config.apiUrl}/auth/session/generate](#operation/auth/session/generate) へパラメータに\`appSecret\`としてシークレットキーを含めたリクエストを送信します。 レスポンスとして認証セッションのトークンや認証フォームのURLが取得できるので、認証フォームのURLをブラウザで表示し、ユーザーにフォームを提示してください。 あなたのアプリがコールバックURLを設定している場合、 @@ -34,14 +33,14 @@ export const description = ` あなたのアプリがコールバックURLを設定していない場合、ユーザーがあなたのアプリの連携を許可したことを(何らかの方法で(たとえばボタンを押させるなど))確認出来るようにしてください。 -#### 3.ユーザートークンを取得する +#### 3.アクセストークンを取得する ユーザーが連携を許可したら、[${config.apiUrl}/auth/session/userkey](#operation/auth/session/userkey) へリクエストを送信します。 -上手くいけば、認証したユーザーのユーザートークンがレスポンスとして取得できます。おめでとうございます！ +上手くいけば、認証したユーザーのアクセストークンがレスポンスとして取得できます。おめでとうございます！ -ユーザートークンが取得できたら、*「ユーザーのユーザートークン+あなたのアプリのシークレットキーをsha256したもの」*をアクセストークンとして、APIにリクエストできます。 +アクセストークンが取得できたら、*「ユーザーのアクセストークン+あなたのアプリのシークレットキーをsha256したもの」*をAPIキーとして、APIにリクエストできます。 -アクセストークンの生成方法を擬似コードで表すと次のようになります: +APIキーの生成方法を擬似コードで表すと次のようになります: \`\`\` js const i = sha256(userToken + secretKey); \`\`\` diff --git a/src/server/api/openapi/gen-spec.ts b/src/server/api/openapi/gen-spec.ts index c8b1c21de4..64da6edbeb 100644 --- a/src/server/api/openapi/gen-spec.ts +++ b/src/server/api/openapi/gen-spec.ts @@ -56,6 +56,7 @@ export function genOpenapiSpec(lang = 'ja-JP') { return { description: (param.data || {}).desc, default: (param.data || {}).default, + deprecated: (param.data || {}).deprecated, ...((param.data || {}).default ? { default: (param.data || {}).default } : {}), type: param.name === 'ID' ? 'string' : param.name.toLowerCase(), ...(param.name === 'ID' ? { example: 'xxxxxxxxxxxxxxxxxxxxxxxx', format: 'id' } : {}), @@ -97,6 +98,7 @@ export function genOpenapiSpec(lang = 'ja-JP') { for (const [k, v] of Object.entries(endpoint.meta.params)) { if (v.validator.data == null) v.validator.data = {}; if (v.desc) v.validator.data.desc = v.desc[lang]; + if (v.deprecated) v.validator.data.deprecated = v.deprecated; if (v.default) v.validator.data.default = v.default; porops[k] = v.validator; }