AsyncAPI

AsyncAPI 仕様を追加するだけで、ネイティブなイベントリファレンスが手に入ります。send と receive の各オペレーションごとに実際のページが生成され、サイドバーと検索に表示されます。

イベント駆動型 API では blume/reference の asyncapi() アダプターを使用し、OpenAPI や GraphQL のアダプターと並べて reference に記述します。openapi() と同じオプションを受け取り、同じネイティブレンダラーで描画されます。各 send/receive オペレーションは実際のページになり、次の内容を備えます。メッセージのペイロードとヘッダーのスキーマテーブル、チャネルパラメーター、プロトコルバインディング、仕様の securitySchemes から導出される Authorization セクション（サーバーレベルとオペレーションレベルの両方に対応し、代替手段は「or」グループとして表示されます）、そして Try it メッセージコンポーザーです。各オペレーションは本物の Blume ページであるため、独自の URL を持ち、サイト検索や llms.txt に表示され、Open Graph 画像も生成されます。これは手書きのドキュメントとまったく同じです。

import { defineConfig } from "blume";
import { asyncapi } from "blume/reference";

export default defineConfig({
  reference: [asyncapi({ spec: "./asyncapi.yaml" })],
});

これにより、リファレンスは /events（概要ページ）にマウントされ、各オペレーションはその配下の個別ページに配置されます。spec には http(s) の URL か、プロジェクト内のローカルファイル（JSON または YAML）へのパスを指定します。他のリファレンスと同様に、これだけではヘッダータブは追加されません。リファレンスを表示してオペレーションのサイドバーの範囲を限定するには、ナビゲーションタブをそのルートに向けてください。

navigation: {
  tabs: [{ label: "Events", path: "/events" }],
}

仕様のバージョン

AsyncAPI 2.x の仕様は、公式の AsyncAPI コンバーターによって自動的に 3.x に正規化されます。そのため、publish/subscribe チャネルは、安定した URL を持つ send/receive オペレーションページに対応付けられます。後から仕様ファイル自体をコンバーターでアップグレードしても、URL は何も変わりません。コンバーターはオプションのピア依存関係のため、1.x または 2.x の仕様を使用するサイトではインストールが必要です（npm install @asyncapi/converter）。インストールされていない場合は、このインストールコマンドを示してビルドが失敗します。3.x の仕様では追加のインストールは不要です。オペレーションはタグごとにグループ化され、タグのないオペレーションはチャネルアドレスごとにグループ化されます。

コードサンプル

コードサンプルはプロトコルに対応しており、オペレーションのバインディング（またはそのサーバーのプロトコル）に応じて切り替わります。WebSocket には wscat とブラウザーの WebSocket スニペット、Kafka には kcat、MQTT には mosquitto_pub/mosquitto_sub が使われます。codeSamples を使うと、openapi() で言語を選ぶのと同じ方法でこのセットを絞り込めます。対応するツールがないプロトコルでは、架空のクライアントをでっち上げるのではなく、メッセージペイロードの例のみを表示します。

共通オプション

OpenAPI で説明している内容は、playground も含めてすべてそのまま使えます。具体的には、route、label/route を指定した sources、expandSchemas、ソースごとのインデックス作成フラグ（seoDescriptionSuffix も含みます。生成される文にはエンドポイントの代わりにチャネルとアクションが記載されます）、そしてオペレーションの概要とタグによる検索インデックス作成です。

代わりに Scalar を埋め込む

asyncapi() は常に Blume 独自のページを描画します。代わりに Scalar の UI を埋め込むには、AsyncAPI ドキュメントを指す scalar() アダプターを記述してください。埋め込まれた Scalar はドキュメントの種類を検出し、チャネル、オペレーション、メッセージ、および Models セクションを描画します。Scalar には AsyncAPI 用のプレイグラウンドがないため、この切り替えではコンポーザーを使えなくなります。また、ソースごとの設定のうち適用されるのは noindex のみです。

イベント向けの 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 オペレーションは API からあなたにメッセージを送るだけなので、接続してログを記録します。再接続の仕組みはありません。ソケットが一度閉じると、再度接続するまで閉じたままです。Kafka、MQTT、AMQP をはじめとするその他のプロトコルでは、コンポーザーとコピー可能な CLI サンプルが提供され、パネルにもその旨がページ上で明示されます。Blume は、ブラウザーのタブからブローカーに接続しているように見せかけることはしません。

asyncapi() の playground は openapi() のものと同じように動作します。ネイティブレンダラーではデフォルトで有効になっており、false を指定するだけで完全に無効にできます。

reference: [asyncapi({ spec: "./asyncapi.yaml", playground: false })],

イベントコンポーザーはブローカーの認証情報を一切収集しません。ブローカーが何を求めるかは、各オペレーションページの Authorization セクションに記載されています。WebSocket 接続で送られるのは、URL にすでに含まれている情報だけです。イベントオペレーションでは、何も保存されません。