From 78a69e3da841ce7bf396f5904876f00f57198395 Mon Sep 17 00:00:00 2001 From: syuilo Date: Sat, 23 Feb 2019 15:35:26 +0900 Subject: Update doc --- src/server/api/gen-openapi-spec.ts | 66 +++++++++++++++++++++++++++++++++++++- 1 file changed, 65 insertions(+), 1 deletion(-) (limited to 'src/server/api') diff --git a/src/server/api/gen-openapi-spec.ts b/src/server/api/gen-openapi-spec.ts index 59dc63228f..5c460d0dae 100644 --- a/src/server/api/gen-openapi-spec.ts +++ b/src/server/api/gen-openapi-spec.ts @@ -267,6 +267,65 @@ const schemas = { } }; +const desc = ` +## Usage +APIはすべてPOSTでリクエスト/レスポンスともにJSON形式です。 +一部のAPIは認証情報(アクセストークン)が必要です。リクエストの際に\`i\`というパラメータでアクセストークンを添付してください。 + +### アクセストークンを取得する +#### 自分のアカウントのアクセストークンを取得する +「設定 > API」で、自分のアクセストークンを取得できます。 + +> アカウントを不正利用される可能性があるため、このトークンは第三者に教えないでください(アプリなどにも入力しないでください)。 + +### アプリケーションとしてアクセストークンを取得する +直接ユーザーのアクセストークンをアプリケーションが扱うのは危険なので、 +アプリケーションからAPIを利用する際には、アプリケーションとアプリケーションを利用するユーザーが結び付けられた専用のアクセストークンをMisskeyに発行してもらいます。 + +#### 1.アプリケーションを登録する +まず、あなたのアプリケーションやWebサービス(以後、あなたのアプリと呼びます)をMisskeyに登録します。 +[デベロッパーセンター](/dev)にアクセスし、「アプリ > アプリ作成」からアプリを作成してください。 +フォームの記入欄の説明は以下の通りです: + +| 名前 | 説明 | +|---|---| +| アプリケーション名 | あなたのアプリの名称。 | +| アプリの概要 | あなたのアプリの簡単な説明や紹介。 | +| コールバックURL | ユーザーが後述する認証フォームで認証を終えた際にリダイレクトするURLを設定できます。あなたのアプリがWebサービスである場合に有用です。 | +| 権限 | あなたのアプリが要求する権限。ここで要求した機能だけがAPIからアクセスできます。 | + +登録が済むとあなたのアプリのシークレットキーが入手できます。このシークレットキーは後で使用します。 + +> アプリに成りすまされる可能性があるため、極力このシークレットキーは公開しないようにしてください。

+ +#### 2.ユーザーに認証させる +アプリを使ってもらうには、ユーザーにアカウントへのアクセスの許可をもらう必要があります。 + +認証セッションを開始するには、%API_URL%/auth/session/generate へパラメータに appSecret としてシークレットキーを含めたリクエストを送信します。 +リクエスト形式はJSONで、メソッドはPOSTです。 +レスポンスとして認証セッションのトークンや認証フォームのURLが取得できるので、認証フォームのURLをブラウザで表示し、ユーザーにフォームを提示してください。 + +あなたのアプリがコールバックURLを設定している場合、 +ユーザーがあなたのアプリの連携を許可すると設定しているコールバックURLに token という名前でセッションのトークンが含まれたクエリを付けてリダイレクトします。 + +あなたのアプリがコールバックURLを設定していない場合、ユーザーがあなたのアプリの連携を許可したことを(何らかの方法で(たとえばボタンを押させるなど))確認出来るようにしてください。 + +#### 3.ユーザートークンを取得する +ユーザーが連携を許可したら、%API_URL%/auth/session/userkey へ次のパラメータを含むリクエストを送信します: + +| 名前 | 型 | 説明 | +|---|---|---| +| appSecret | string | アプリのシークレットキー | +| token | string | セッションのトークン | + +上手くいけば、認証したユーザーのユーザートークンがレスポンスとして取得できます。おめでとうございます！ + +ユーザートークンが取得できたら、「ユーザーのユーザートークン+あなたのアプリのシークレットキーをsha256したもの」をアクセストークンとして、APIにリクエストできます。 + +アクセストークンの生成方法を擬似コードで表すと次のようになります: +
const i = sha256(userToken + secretKey);
+`; + export function genOpenapiSpec(lang = 'ja-JP') { const spec = { openapi: '3.0.0', @@ -274,10 +333,15 @@ export function genOpenapiSpec(lang = 'ja-JP') { info: { version: 'v1', title: 'Misskey API', - description: 'Misskey is a decentralized microblogging platform.', + description: '**Misskey is a decentralized microblogging platform.**\n\n' + desc, 'x-logo': { url: '/assets/api-doc.png' } }, + externalDocs: { + description: 'Repository', + url: 'https://github.com/syuilo/misskey' + }, + servers: [{ url: config.api_url }], -- cgit v1.2.3-freya