diff --git a/src/client/pages/doc.vue b/src/client/pages/doc.vue
index e0db5a374..5cdb5999b 100644
--- a/src/client/pages/doc.vue
+++ b/src/client/pages/doc.vue
@@ -72,6 +72,9 @@ export default Vue.extend({
 		},
 
 		parse(md: string) {
+			// 変数置換
+			md = md.replace(/\{_URL_\}/g, url);
+
 			// markdown の全容をパースする
 			const parsed = markdown.parse(md, {});
 			if (parsed.length === 0) return;
diff --git a/src/docs/api.ja-JP.md b/src/docs/api.ja-JP.md
index 6e1eba065..5d370a29c 100644
--- a/src/docs/api.ja-JP.md
+++ b/src/docs/api.ja-JP.md
@@ -1,3 +1,60 @@
 # Misskey API
 
-[APIリファレンス](/api-doc)
+MisskeyAPIを使ってMisskeyクライアント、Misskey連携Webサービス、Bot等(以下「アプリケーション」と呼びます)を開発できます。
+ストリーミングAPIもあるので、リアルタイム性のあるアプリケーションを作ることも可能です。
+
+APIを使い始めるには、まずAPIキーを取得する必要があります。
+このドキュメントでは、APIキーを取得する手順を説明した後、基本的なAPIの使い方を説明します。
+
+## APIキーの取得
+基本的に、APIはリクエストにはAPIキーが必要となります。
+あなたの作ろうとしているアプリケーションが、あなた専用のものなのか、それとも不特定多数の人に使ってもらうものなのかによって、APIキーの取得手順は異なります。
+
+* あなた専用の場合: [「自分のアカウントのAPIキーを取得する」](#自分のアカウントのAPIキーを取得する)に進む
+* 皆に使ってもらう場合: [「アプリケーションとしてAPIキーを取得する」](#アプリケーションとしてAPIキーを取得する)に進む
+
+### 自分のアカウントのAPIキーを取得する
+「設定 > API」で、自分のAPIキーを取得できます。
+
+> この方法で入手したAPIキーは強力なので、第三者に教えないでください(アプリなどにも入力しないでください)。
+
+[「APIの使い方」へ進む](#APIの使い方)
+
+### アプリケーションとしてAPIキーを取得する
+アプリケーションを使ってもらうには、ユーザーのAPIキーを以下の手順で取得する必要があります。
+
+#### Step 1
+
+UUIDを生成する。以後これをセッションIDと呼びます。
+
+#### Step 2
+
+`{_URL_}/miauth/{session}`をユーザーのブラウザで表示させる。`{session}`の部分は、セッションIDに置き換えてください。
+> 例: `{_URL_}/miauth/c1f6d42b-468b-4fd2-8274-e58abdedef6f`
+
+表示する際、URLにクエリパラメータとしていくつかのオプションを設定できます:
+* `name` ... アプリケーション名
+	* > 例: `MissDeck`
+* `callback` ... 認証が終わった後にリダイレクトするURL
+	* > 例: `https://missdeck.example.com/callback`
+	* リダイレクト時には、`session`というクエリパラメータでセッションIDが付きます
+* `permissions` ... アプリケーションが要求する権限
+	* > 例: `write:notes,write:following,read:drive`
+	* 要求する権限を`,`で区切って列挙します
+	* どのような権限があるかは[APIリファレンス](/api-doc)で確認できます
+
+#### Step 3
+ユーザーが連携を許可した後、`{_URL_}/miauth/{session}/check`にPOSTリクエストすると、レスポンスとしてAPIキーを含むJSONが返ります。
+
+レスポンスに含まれるプロパティ:
+* `token` ... ユーザーのAPIキー
+* `user` ... ユーザーの情報
+
+[「APIの使い方」へ進む](#APIの使い方)
+
+## APIの使い方
+**APIはすべてPOSTで、リクエスト/レスポンスともにJSON形式です。RESTではありません。**
+APIキーは、`i`というパラメータ名でリクエストに含めます。
+
+* [APIリファレンス](/api-doc)
+* [ストリーミングAPI](./stream)
diff --git a/src/server/api/openapi/description.ts b/src/server/api/openapi/description.ts
index a4b79d950..4fff53ac9 100644
--- a/src/server/api/openapi/description.ts
+++ b/src/server/api/openapi/description.ts
@@ -42,52 +42,7 @@ export function getDescription(lang = 'ja-JP'): string {
 		.join('\n');
 
 	const descriptions = {
-		'ja-JP': `**Misskey is a decentralized microblogging platform.**
-
-# Usage
-**APIはすべてPOSTでリクエスト/レスポンスともにJSON形式です。**
-一部のAPIはリクエストに認証情報(APIキー)が必要です。リクエストの際に\`i\`というパラメータでAPIキーを添付してください。
-
-## 自分のアカウントのAPIキーを取得する
-「設定 > API」で、自分のAPIキーを取得できます。
-
-> アカウントを不正利用される可能性があるため、このトークンは第三者に教えないでください(アプリなどにも入力しないでください)。
-
-## アプリケーションとしてAPIキーを取得する
-直接ユーザーのAPIキーをアプリケーションが扱うのはセキュリティ上のリスクがあるので、
-アプリケーションからAPIを利用する際には、アプリケーションとアプリケーションを利用するユーザーが結び付けられた専用のAPIキーを発行します。
-
-### 1.アプリケーションを登録する
-まず、あなたのアプリケーションやWebサービス(以後、あなたのアプリと呼びます)をMisskeyに登録します。
-[デベロッパーセンター](/dev)にアクセスし、「アプリ > アプリ作成」からアプリを作成してください。
-
-登録が済むとあなたのアプリのシークレットキーが入手できます。このシークレットキーは後で使用します。
-
-> アプリに成りすまされる可能性があるため、極力このシークレットキーは公開しないようにしてください。</p>
-
-### 2.ユーザーに認証させる
-アプリを使ってもらうには、ユーザーにアカウントへのアクセスの許可をもらう必要があります。
-
-認証セッションを開始するには、[${config.apiUrl}/auth/session/generate](#operation/auth/session/generate) へパラメータに\`appSecret\`としてシークレットキーを含めたリクエストを送信します。
-レスポンスとして認証セッションのトークンや認証フォームのURLが取得できるので、認証フォームのURLをブラウザで表示し、ユーザーにフォームを提示してください。
-
-あなたのアプリがコールバックURLを設定している場合、
-ユーザーがあなたのアプリの連携を許可すると設定しているコールバックURLに\`token\`という名前でセッションのトークンが含まれたクエリを付けてリダイレクトします。
-
-あなたのアプリがコールバックURLを設定していない場合、ユーザーがあなたのアプリの連携を許可したことを(何らかの方法で(たとえばボタンを押させるなど))確認出来るようにしてください。
-
-### 3.アクセストークンを取得する
-ユーザーが連携を許可したら、[${config.apiUrl}/auth/session/userkey](#operation/auth/session/userkey) へリクエストを送信します。
-
-上手くいけば、認証したユーザーのアクセストークンがレスポンスとして取得できます。おめでとうございます！
-
-アクセストークンが取得できたら、*「ユーザーのアクセストークン+あなたのアプリのシークレットキーをsha256したもの」*をAPIキーとして、APIにリクエストできます。
-
-APIキーの生成方法を擬似コードで表すと次のようになります:
-\`\`\` js
-const i = sha256(userToken + secretKey);
-\`\`\`
-
+		'ja-JP': `
 # Permissions
 |Permisson (kind)|Description|Endpoints|
 |:--|:--|:--|