---
title: OpenAPI / AsyncAPI
description: >-
  OpenAPI または AsyncAPI 仕様を投入するだけでネイティブな API リファレンスを生成 — 操作ごとに 1 つの実ページを、サイドバーと検索に。
---

Blume に OpenAPI 仕様を指定すると、ネイティブな API リファレンスを生成します。**操作ごとに 1 つの実ページ**が作られ、タブスコープのサイドバーでタグごとにグループ化され、スキーマの表、リクエスト/レスポンスの例、生成されたコードサンプル、そしてインタラクティブな [Try it](#try-it-playground) パネルが付きます。各操作は正真正銘の Blume ページなので、独自の URL を持ち、**サイト検索**や `llms.txt` に現れ、Open Graph 画像も生成されます — 手書きのドキュメントとまったく同じです。以下の設定では、例として公開されている Petstore 仕様を Blume に指定しています。

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "https://petstore3.swagger.io/api/v3/openapi.json",
}
```

これでリファレンスが `/reference`（概要ページ）にマウントされ、各操作は `/reference/<tag>/<operation>` に配置されます。`spec` は `http(s)` の URL か、プロジェクト内のローカルファイルへのパスのいずれかです。Blume は [Scalar の OpenAPI パーサー](https://github.com/scalar/scalar)で解析します — Swagger 2.0 および OpenAPI 3.0 の仕様は自動的に 3.1 へアップグレードされます。代わりに GraphQL API をドキュメント化しますか？ [GraphQL リファレンス](/docs/advanced/graphql)をご覧ください。

リファレンスはそれ自体ではヘッダータブを追加しません。表に出すには、[ナビゲーションタブ](/docs/content/navigation#tabs)をそのルートに向けてください — これによりネイティブレンダラーの操作サイドバーのスコープも設定されます。

```ts blume.config.ts
navigation: {
  tabs: [{ label: "API", path: "/reference" }],
}
```

:::note
操作は**サマリーとタグ**によって検索用にインデックスされます。レンダリングされたスキーマの表やコードサンプルは全文インデックスされません。検索は操作のタイトルとセクションにマッチし、その操作自身のページへリンクします。
:::

## ローカルの仕様 [#a-local-spec]

相対パスはプロジェクトルートを基点に解決され、ビルド時に読み込まれます。JSON と YAML のどちらも利用できます。

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "./openapi.yaml",
}
```

## ルート [#route]

`route` はリファレンスのマウント先を制御します — 概要ページと、すべての操作ルートのプレフィックス（およびナビゲーションタブを向ける先のルート）です。

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  route: "/api",   // overview at /api, operations at /api/<tag>/<operation>
  spec: "./openapi.yaml",
}
```

## コードサンプルとスキーマ [#code-samples-and-schemas]

`codeSamples` は操作ごとにどの言語をレンダリングするかを選びます（組み込み: `curl`、`js`、`python`）。`expandSchemas` はネストしたスキーマの行を折りたたまずに展開した状態で開始します。

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  codeSamples: ["curl", "js"],
  expandSchemas: true,
}
```

## Try it プレイグラウンド [#try-it-playground]

ネイティブにレンダリングされた操作ページには、デフォルトでインタラクティブな **Try it** パネルが付属します。Blume は操作そのものからフォームを生成します。パス、クエリ、ヘッダーの各パラメーターごとの入力欄、リクエストボディのスキーマから構築されたボディエディター、そしてそのすべてが仕様の例で事前入力されます。サーバーピッカーには仕様の `servers` が一覧表示され、それ以外のベース URL 用に自由入力欄も用意されています。認証の入力欄は操作の[解決されたセキュリティ](#authorization)に一致します — ベアラートークン、API キー、ベーシック資格情報、そして OAuth2 はトークンの貼り付け欄として提供されます（アクセストークンはご自身でご用意ください。Blume はフローを実行しません）。

パネルとコードサンプルは常に同期します。フォームに入力した値は生成されるサンプルにリアルタイムで反映されるため、コピーした curl コマンドは **Send** の動作と常に完全に一致します。しかも邪魔になりません。パネルは折りたたまれた状態でサーバーレンダリングされ、その JavaScript は読者が最初に開いたときにのみ読み込まれます。一度も触れない読者は、そのいずれもダウンロードしません。

`playground: false` がオフスイッチのすべてです。

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  playground: false,
}
```

### 資格情報 [#credentials]

認証の入力欄に入力された資格情報はメモリー上に留まり、再読み込みで消えます。**Remember on this device** をチェックすると、ドキュメントのオリジンにスコープされた `localStorage` に保存されます — 呼び出し対象の API 以外へ送信されることは決してありません。読者が **Include my values in samples** を切り替えない限り、コードサンプルには何を入力してもプレースホルダー（`YOUR_TOKEN` など）が表示され続けます。

### CORS とプロキシ [#cors-and-the-proxy]

[Scalar レンダラー](#the-scalar-renderer)と同様に、リクエストは**ブラウザーから直接**対象の API へ送られるため、API はドキュメントサイトからのクロスオリジンリクエストを許可する必要があります（`Access-Control-Allow-Origin`）。それができない API には `playground.proxy` を設定してください。URL を指定すると自前でホストしたプロキシ経由でリクエストが送られ、`true` にすると組み込みの `/_api-proxy` ルートが有効になります — これはサーバービルドを必要とするため、[`deployment.output: "server"`](/docs/deployment#server-rendering) が必要です。

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  playground: {
    proxy: true,   // or a URL of your own
  },
}
```

組み込みプロキシは、仕様が `servers` で宣言したオリジンにのみリクエストを転送します — リダイレクトをまたいだ場合も同様です — そのため、公開されたドキュメントのデプロイメントをネットワーク上の他のホストへ向けることはできません。パネルに入力された **Custom base URL** はドキュメント化されたサーバーではありません。プロキシを有効にしている場合、そこへのリクエストは 403 で拒否されます。

## 複数の仕様 [#multiple-specs]

複数の仕様を公開するには `sources` を使います。各ソースは独自の概要ルート、操作ページ、ヘッダータブを持ちます。それぞれに `label`（タブに使われ、ルートの導出にも使われます）を与えるか、明示的に `route` を設定してください。

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  sources: [
    { label: "Public API", spec: "./public.json" },   // → /reference/public-api
    { label: "Admin API", route: "/admin", spec: "./admin.json" },
  ],
}
```

`spec` はエントリが 1 つだけの `sources` の短縮形なので、`sources` を使うのは仕様が複数ある場合だけです。

### ソースごとのインデックス [#per-source-indexing]

生成されたページは、デフォルトで検索、`llms.txt`、クローラーのインデックスの対象になります。副次的な仕様や内容が重複する仕様は、ページを非表示にしたりナビゲーションから外したりすることなく、任意の対象から除外できます。

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  sources: [
    { label: "Public API", route: "/api", spec: "./public.json" },
    {
      label: "Platform API",
      route: "/platform",
      spec: "./platform.json",
      includeInSearch: false,
      includeInLlms: false,
      noindex: true,
    },
  ],
}
```

- `includeInSearch: false` は、そのソースの概要と操作をサイト検索から除外します。
- `includeInLlms: false` は、両方の `llms.txt` ファイルから除外します。
- `noindex: true` は、クローラー向けの noindex メタデータを追加し、サイトマップからページを削除します。

各操作ページのメタディスクリプションは、その操作自身の `description`（または `summary`）に続けて、エンドポイント名を挙げる生成された一文 — 「Reference for the `GET /pets` endpoint in the Petstore API.」 — が付いたものです。そのため、簡潔な一行のサマリーしかない仕様でも、ページごとに固有でスニペットに適した長さの説明文が出力されます。この一文は英語です。仕様の文章が英語以外で書かれているサイトでは、ソースに `seoDescriptionSuffix: false` を設定してこれを削除し、執筆された文章だけで各ページを説明してください。`description` も `summary` も持たない操作はタイトル（`GET /pets`）にフォールバックするため、説明文が空のページが出力されることはありません。

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  sources: [{ spec: "./openapi.de.json", seoDescriptionSuffix: false }],
}
```

[Scalar レンダラー](#the-scalar-renderer)では `noindex` のみが適用されます — Scalar でレンダリングされたリファレンスはもともと Blume の検索や `llms.txt` の外側にあるため、2 つの `include*` 設定はそこでは作用する対象がありません。

## 認可 [#authorization]

[セキュリティ要件](https://spec.openapis.org/oas/v3.1.0#security-requirement-object)を宣言している操作は、パラメーターの上に**認可**セクションをレンダリングし、生成されたコードサンプルはプレースホルダーの資格情報（`Authorization: Bearer YOUR_TOKEN`、API キーヘッダー、クエリキーなど、スキームが要求するもの）を送信します。設定は不要です。Blume は仕様から `security` を読み取るため、リファレンスは常に API が実際に強制している内容と一致します。

OpenAPI のセマンティクスはそのまま引き継がれます。

- 操作自身の `security` はドキュメントのルートのデフォルトを上書きします。`security: []` はその操作を**パブリック**として示し、認可セクションはレンダリングされません。
- 複数の要件エントリは選択肢を表し、「or」グループとしてレンダリングされます。1 つのエントリ内のすべてのスキームはまとめて必須です。最初の選択肢がコードサンプルに使われます。
- 空の `{}` エントリは、その操作で認証が**任意**であることを意味し、セクションにもそのように表示されます。
- OAuth2 のスコープはスキームごとに一覧表示され、`components.securitySchemes` のスキームの `description` はインラインでレンダリングされます。

## Scalar レンダラー [#the-scalar-renderer]

ネイティブレンダラーがデフォルトです — 上で説明した操作ページ、検索の統合、[Try it プレイグラウンド](#try-it-playground)は、すべてこのレンダラーによるものです。[Scalar](https://scalar.com) の自己完結型 API リファレンス UI — 独自のサイドバー、検索、テーマ、そして単一ルート上のリクエストクライアント — を埋め込みたい場合は、`renderer: "scalar"` を設定してください。

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  renderer: "scalar",
  spec: "./openapi.yaml",
  theme: "purple",   // a Scalar theme name (Scalar renderer only)
}
```

Scalar でレンダリングされたリファレンスは、独自のルート上にある自己完結型の埋め込みです — Blume のサイドバー、検索、`llms.txt` には組み込まれず、Blume の [`playground`](#try-it-playground) 設定も適用されません。ただし Blume のライト/ダークの切り替えには従います。埋め込みはマウント時にページのテーマに固定され、それに合わせて切り替わるため、Scalar 自身のテーマ切り替えは非表示になります（カラーモードを Scalar 側に戻すには `scalar.forceDarkModeState` または `scalar.darkMode` を設定してください）。Scalar は独自のリクエストクライアントを備えており、**ブラウザーから対象の API を直接**呼び出す（`playground.proxy` のルートはここでは利用できません）ため、API はドキュメントサイトからのクロスオリジンリクエストを許可する必要があります（`Access-Control-Allow-Origin`）。`theme` は Scalar レンダラーにのみ適用されます。

### Scalar のオプションを渡す [#passing-scalar-options]

`theme` は最も多くの人が使うオプション 1 つの短縮形ですが、Scalar はさらに多くのオプションをサポートしています。`scalar` オブジェクトは、任意の [Scalar 設定](https://github.com/scalar/scalar/blob/main/documentation/configuration.md)を埋め込みリファレンスへそのまま転送します — Blume はキーを制限しないため、Scalar が受け付けるものはすべて通過します。

```ts blume.config.ts lineNumbers
openapi: {
  enabled: true,
  renderer: "scalar",
  spec: "./openapi.yaml",
  scalar: {
    localization: { locale: "es" },   // translate Scalar's own UI
    agent: { disabled: true },         // disable the Scalar Agent
    hideTestRequestButton: true,
    orderSchemaPropertiesBy: "preserve",
  },
}
```

Blume 自身の [`i18n`](/docs/content/i18n) はドキュメントの外装を翻訳しますが、Scalar には別のローカライズ機構があります — 埋め込みリファレンスも翻訳するには `scalar.localization.locale` を設定してください。`scalar` オブジェクト内のオプションは Blume が導出した設定より優先されるため、ここで設定したもの（`theme`、`customCss`、仕様の `content`/`url` を含む）は Blume のデフォルトを上書きします。同じ `scalar` ブロックは `asyncapi` リファレンスでも機能します。

## AsyncAPI

イベント駆動 API は、同じ形をした兄弟の `asyncapi` ブロックを使います — そして同じネイティブレンダラーを使います。各 `send`/`receive` 操作は、メッセージペイロードとヘッダースキーマの表、チャネルパラメーター、プロトコルバインディング、仕様の `securitySchemes` から導出された認可セクション（サーバーレベルと操作レベルの両方、選択肢は「or」グループとして表示）、そして [Try it](#try-it-for-events) メッセージコンポーザーを備えた実ページになります。異なるのはデフォルトのルートだけです（`/events`）:

```ts blume.config.ts lineNumbers
asyncapi: {
  enabled: true,
  spec: "./asyncapi.yaml",
}
```

AsyncAPI **2.x の仕様は、公式の AsyncAPI コンバーターによって自動的に 3.x へ正規化されます**。そのため `publish`/`subscribe` チャネルは、安定した URL を持つ `send`/`receive` の操作ページにマッピングされます — 後から仕様ファイル自体をコンバーターでアップグレードしても、何も移動しません。操作はタグごとにグループ化され、タグのない操作はチャネルアドレスの下にグループ化されます。

コードサンプルは**プロトコル対応**で、操作のバインディング（またはそのサーバーのプロトコル）に基づいて選ばれます。WebSocket には `wscat` とブラウザーの `WebSocket` スニペット、Kafka には `kcat`、MQTT には `mosquitto_pub`/`mosquitto_sub` です。`codeSamples` は、`openapi` ブロックで言語を選ぶのと同じ方法でそのセットを絞り込みます。サポートされているツールがないプロトコルでは、でっち上げのクライアントを生成する代わりに、メッセージペイロードの例のみをレンダリングします。

上で説明した内容はすべてそのまま引き継がれます。[`playground`](#try-it-for-events) も含めて: `route`、`label`/`route` 付きの `sources`、`expandSchemas`、[ソースごとのインデックス](#per-source-indexing)のフラグ（`seoDescriptionSuffix` も含みます — 生成される一文はエンドポイントではなくチャネルとアクションを挙げます）、そして操作のサマリーとタグによる検索インデックスです。

`renderer: "scalar"` を設定すると埋め込みの Scalar SPA に戻れます。そこでは、OpenAPI と同様に `noindex` のみが適用されます。Scalar には独自の AsyncAPI プレイグラウンドはありません。その埋め込みはドキュメントタイプを自動検出し、チャネル、操作、メッセージ、Models セクションをレンダリングするため、この切り替えではコンポーザーを手放すことになります。

### イベント向けの Try it [#try-it-for-events]

ネイティブにレンダリングされた操作ページには、ここでも **Try it** パネルが付属し、[OpenAPI のパネル](#try-it-playground)と同じ条件が適用されます。折りたたまれた状態でサーバーレンダリングされ、その JavaScript は読者が最初に開いたときにのみ読み込まれます。

プロトコルが何であれ、パネルはメッセージの `examples` から事前入力されたペイロードエディターとともに開きます — メッセージが例を宣言していない場合は、ペイロードスキーマからサンプリングされた値が使われます — 入力中はメッセージペイロードのスキーマに対して検証されます。その下には、チャネルパラメーターごとの入力欄と、チャネルの `servers` を元にしたサーバーピッカーがあり、それ以外の URL 用に自由入力欄も用意されています。プロトコル対応のコードサンプルは、HTTP 操作における curl、js、python とまったく同じようにフォームと同期し続けます。チャネルアドレスのテンプレートには入力したパラメーターの値が埋め込まれるため、コピーした `wscat`、`WebSocket`、`kcat`、`mosquitto_pub` のスニペットはフォームの内容に一致します。

ライブ接続は WebSocket 専用です。`ws` または `wss` のバインディングでは、パネルは解決されたチャネル URL へ接続し、接続状態を表示し、すべてのフレームをタイムスタンプ付きでログに記録します。AsyncAPI 3 はアクションを API 側の視点で表現しており、パネルもそれに従います。`receive` 操作は API があなたから受け取る操作なので、作成したペイロードを送信する **Send** ボタンが付きます。`send` 操作はあなたに向けてメッセージをストリーミングするだけなので、接続してログに記録します。再接続のロジックはありません — ソケットが一度閉じると、再度接続するまで閉じたままです。Kafka、MQTT、AMQP、その他すべてのプロトコルではコンポーザーとコピー可能な CLI サンプルが提供され、パネルにもページ上でその旨が表示されます。Blume はブラウザーのタブからブローカーへの接続を偽装したりはしません。

`asyncapi.playground` は `openapi.playground` と対になっています — ネイティブレンダラーではデフォルトで有効で、`false` がオフスイッチのすべてです。

```ts blume.config.ts lineNumbers
asyncapi: {
  enabled: true,
  spec: "./asyncapi.yaml",
  playground: false,
}
```

:::note
`playground.proxy` はイベント操作には適用されません。これは HTTP リクエストを転送するものであり、WebSocket の接続はブラウザーから URL に指定されたサーバーへ直接向かうため、プロキシが前段に入る対象がありません。
:::

イベントのコンポーザーはブローカーの資格情報を一切収集しません。各操作ページの**認可**セクションはブローカーが要求する内容を説明し、WebSocket の接続は URL にすでに含まれているものだけを伝えます。イベント操作では何も永続化されません。