sim1222/nca10.net
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Improve doc

Browse Source
This commit is contained in:
syuilo
2019-02-25 04:18:09 +09:00
parent 47d4dcfdf5
commit 60c9a6528f
14 changed files with 52 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
src/server/api/openapi/description.ts
View File

@ -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);
\`\`\`

2
src/server/api/openapi/gen-spec.ts
View File

@ -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;
}