コンテンツにスキップ
Blume
日本語
EnglishDeutschहिन्दी日本語Português
Esc
↑↓移動↵開く⌘Jプレビュー
このページの内容

OpenAPI / AsyncAPI

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

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

openapi: {
  enabled: true,
  spec: "https://petstore3.swagger.io/api/v3/openapi.json",
}

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

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

navigation: {
  tabs: [{ label: "API", path: "/reference" }],
}

ローカルの仕様

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

openapi: {
  enabled: true,
  spec: "./openapi.yaml",
}

ルート

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

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

コードサンプルとスキーマ

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

openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  codeSamples: ["curl", "js"],
  expandSchemas: true,
}

Try it プレイグラウンド

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

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

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

openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  playground: false,
}

資格情報

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

CORS とプロキシ

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

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

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

複数の仕様

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

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 を使うのは仕様が複数ある場合だけです。

ソースごとのインデックス

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

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）にフォールバックするため、説明文が空のページが出力されることはありません。

openapi: {
  enabled: true,
  sources: [{ spec: "./openapi.de.json", seoDescriptionSuffix: false }],
}

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

認可

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

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

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

Scalar レンダラー

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

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

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

Scalar のオプションを渡す

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

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

AsyncAPI

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

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 も含めて: route、label/route 付きの sources、expandSchemas、ソースごとのインデックスのフラグ（seoDescriptionSuffix も含みます — 生成される一文はエンドポイントではなくチャネルとアクションを挙げます）、そして操作のサマリーとタグによる検索インデックスです。

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

イベント向けの Try it

ネイティブにレンダリングされた操作ページには、ここでも Try it パネルが付属し、OpenAPI のパネルと同じ条件が適用されます。折りたたまれた状態でサーバーレンダリングされ、その 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 がオフスイッチのすべてです。

asyncapi: {
  enabled: true,
  spec: "./asyncapi.yaml",
  playground: false,
}

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

最終更新 2026年9月9日

このページは役に立ちましたか？