OpenAPI

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

Blume に OpenAPI 仕様を指定すると、ネイティブな API リファレンスが生成されます。オペレーションごとに実際のページが作られ、タブ単位のサイドバーでタグごとにグループ化されます。各ページにはスキーマテーブル、リクエスト/レスポンスの例、生成されたコードサンプル、インタラクティブな Try it パネルが含まれます。各オペレーションは本物の Blume ページなので、手書きのドキュメントと同じように独自の URL を持ち、サイト検索や llms.txt に表示され、Open Graph 画像も生成されます。

すべてのリファレンスは、blume/reference からインポートして reference の下に列挙するアダプターです。OpenAPI ドキュメントには openapi()、AsyncAPI ドキュメントには asyncapi()、GraphQL スキーマには graphql() を使います。各アダプターは独自の仕様ソース、マウントルート、表示オプションを持つため、リストには各種類のアダプターを必要なだけ含められます。以下の設定では、例として公開されている Petstore 仕様を Blume に指定しています。

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

export default defineConfig({
  reference: [
    openapi({ 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 にアップグレードされ、3.1 と 3.2 の仕様は記述されたまま読み込まれます。アダプターは解析済みの仕様ではなく、リファレンスを記述したプレーンな設定です。そのため Blume は事前に検証を行い、生成されるサイトにインライン化できます。reference を省略する（または空にする）と、リファレンスは一切レンダリングされません。イベント駆動型 API や GraphQL API をドキュメント化する場合は、AsyncAPI と GraphQL を参照してください。

フレームワークが生成した仕様からリファレンスをデプロイするまでの手順については、FastAPI、Django REST Framework、NestJS、Spring Boot、ASP.NET Core、Laravel、Rails、Hono、Fastify、Elysia、oRPC の各ガイドを参照してください。API を TypeSpec で定義している場合は、TypeSpec の定義から公開できます。OpenAPI 仕様から API ドキュメントを生成するでは、任意の仕様ファイルを出発点として説明しています。

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

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

サイドバーのタググループと概要ページのセクションは、同じ順序で並びます。まず仕様のトップレベルの tags リストの順序で並び、その後に tags で宣言されていないタグが、オペレーションで最初に使われた順に続きます。タグ内のオペレーションも仕様の順序に従います。パスは列挙された順に、各パスのメソッドは記述された順に並びます。タグのフォルダーに独自の pages リストを持つ meta.ts を置くと、この順序を上書きできます。

Redocly の拡張であるタグの x-displayName を指定すると、タグ名の代わりにその値がサイドバーのグループと概要ページのセクションのラベルになります。URL は引き続きタグ名から生成されるため、x-displayName を追加してもページの場所は変わりません。オペレーションのラベルには summary が使われ、summary がない場合はページのタイトルと同様にメソッドとパス（GET /pets）が使われます。

仕様の info.description は概要ページの冒頭に、各タグの description は概要ページ内のそのタグのセクションの冒頭に表示されます。これらに含まれる見出しは、配置される位置に合わせて 1 レベル下げられるため、ページのタイトルが唯一のトップレベルの見出しのまま保たれます。info.description やオペレーションの description に含まれる # Authentication は第 2 レベルの見出しとして、タグの説明に含まれる場合はタグ自身の見出しの下の第 3 レベルの見出しとしてレンダリングされます。

ローカルの仕様

相対パスはプロジェクトルートから解決され、ビルド時に読み込まれます。JSON と YAML のどちらも使えます。また、blume dev はこのファイルをローカルのオーバーレイとあわせて監視するため、仕様を保存するとリファレンスが更新されます。

reference: [openapi({ spec: "./openapi.yaml" })],

OpenAPI 3.2

OpenAPI 3.2 の仕様は記述されたとおりにレンダリングされます。HTTP の QUERY メソッド（ボディを伴う安全なリクエスト）を表す query オペレーションにも、他のメソッドと同様にページ、Try it、コードサンプルが用意されます。3.2 で追加されたフィールドのうち Blume が表示しないもの（タグやレスポンスの summary など）は、エラーにはならず無視されます。3.2 で追加された機能の中には、まだレンダリングされないものもあります。

• additionalOperations（COPY のように、パスアイテムで直接指定されないメソッドに使われます）：これらのオペレーションは除外され、BLUME_OPENAPI_UNSUPPORTED の警告が表示されます。
• in: querystring パラメーター：パラメーターテーブルの行、Try it の入力欄、コードサンプルのいずれにも反映されず、同じ警告が表示されます。
• itemSchema（text/event-stream や application/jsonl のようにストリーミングされるボディの、各項目のスキーマ）：並べて schema を設定しない限り、そのボディのスキーマはページに表示されません。
• value の代わりに dataValue または serializedValue で記述された例：ページには表示されません。
• ネストされたタグ（parent）とタグの kind：タグはサイドバーと概要ページで 1 つのフラットなリストのまま表示されます。

ルート

route は、リファレンスをマウントする場所を制御します。これは概要ページの場所であり、すべてのオペレーションルートのプレフィックス（およびナビゲーションタブを向けるルート）でもあります。

reference: [
  openapi({
    route: "/api",   // overview at /api, operations at /api/<tag>/<operation>
    spec: "./openapi.yaml",
  }),
],

オペレーションの <tag> は最初のタグ（タグがない場合は operations）で、<operation> は operationId、それがない場合はメソッドとパスです。どちらも小文字に変換され、単語はハイフンで区切られます。これは camelCase や PascalCase にも適用され、タグ InboxesThreads は inboxes-threads に、operationId listThreads は list-threads になります。オペレーションのスラッグはタグ内で一意であればよいため、2 つのタグがそれぞれ list を持つことができます。同じタグ内の 2 つ目の list にはメソッドが付加され（list-post）、2 つが同じ operationId を共有している場合は BLUME_OPENAPI_DUPLICATE_OPERATION_ID の警告が表示されます。

以前のバージョンの Blume では、タグの単語は区切られず（inboxesthreads）、オペレーションのスラッグは仕様全体で一意になるように生成されていました（2 つ目の list は list-get）。Blume はこれらの各 URL とその Markdown 版を、ページの現在の URL にリダイレクトします。ただし、その URL にすでにページや独自の redirects がある場合は除きます。

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

codeSamples は、オペレーションごとにレンダリングする言語を、列挙した順序で選択します。デフォルトは ["curl", "js", "python"] で、false または空のリストを指定すると何も表示されません。expandSchemas を指定すると、ネストされたスキーマ行が折りたたまれた状態ではなく、展開された状態で表示されます。

reference: [
  openapi({
    spec: "./openapi.yaml",
    codeSamples: ["curl", "python", "go", "java", "csharp"],
    expandSchemas: true,
  }),
],

各サンプルは、リクエストをそのままコピー＆ペーストして使えるプレーンなコードで、各言語の標準または最も一般的な HTTP クライアントを使って書かれています。

各値はそれぞれの言語の規則に従ってクォートされます。そのため、If-Match: "33a64df5" のようなヘッダーや $ を含むボディも、記述したとおりに API に届きます。

ReadMe の objectivec のように Blume がサンプルを生成しない ID は、すべてのページで除外され、上記の ID を列挙した BLUME_OPENAPI_UNKNOWN_CODE_SAMPLE の警告が表示されます。他の言語のサンプルを表示するには、独自のサンプルとして仕様に記述してください。

スキーマテーブルは、例と同様に、データが流れる方向に従います。リクエストボディでは、サーバーが設定する readOnly プロパティが省かれ、レスポンスでは、サーバーが返すことのない writeOnly プロパティが省かれます。Webhook やコールバックのボディは API が送信するリクエストなので、レスポンスと同じように表示されます。リクエストのサンプル、Try it フォームとその初期値、レスポンスの例も同様です。これには、モデルの id を含むモデルレベルの example のように、仕様に記述された例も含まれます。

examples マップに 2 つ以上の例が指定されたボディやレスポンスでは、それぞれの例が summary（ない場合はキー）をラベルとして表示されます。レスポンスではステータスの後に例ごとのタブ（200 · A cat）が、Webhook のペイロードではメディアタイプの後に例ごとのタブが表示され、リクエストボディではスキーマの下に Examples ブロックが表示されます。コードサンプルと Try it には最初の例が使われます。

OpenAPI 3.1 では $ref と並べてキーワードを記述できます。このように記述されたプロパティでは、参照先のスキーマのキーワードよりも並べて記述したキーワードが優先されます。行にはプロパティ自身の description が表示され、サンプルにはプロパティ自身の example または default が使われます。

独自のサンプル

生の HTTP 呼び出しの代わりにご自身の SDK を示すには、仕様内のオペレーションに x-codeSamples を追加します。これは Redocly が定義した拡張で、Speakeasy や Stainless で自動的に書き出すこともできます。各エントリには lang、source、および任意の label を指定します。

paths:
  /plants:
    get:
      x-codeSamples:
        - lang: typescript
          label: SDK
          source: |
            const plants = await planter.plants.list();
        - lang: bash
          label: CLI
          source: |
            planter list

これらのサンプルは、生成されたサンプルより前に独立したタブとしてレンダリングされます。読者が Try it フォームの値を変更しても、記述したとおりの内容のまま表示されます。旧来の x-code-samples という表記も使えます。独自のサンプルだけを表示するには、codeSamples: false を設定してください。生成されたサンプルとは異なり、これらはオペレーションページの Markdown 版にも含まれるため、llms-full.txt、MCP サーバー、アシスタントからもご自身の SDK の呼び出しを参照できます。この Markdown 版には、リクエストボディのメディアタイプとトップレベルのプロパティがその例（名前付きの例はすべて）とともに列挙され、各レスポンスのステータスと説明も、仕様に記録された例とともに列挙されます。例が記録されていない最初の成功レスポンスには、スキーマから生成された例が付きます。

Redocly がサンプルを独立したファイルに保存する方法として説明しているように、source にはサンプルのコードを収めたファイルへの $ref も指定できます。Blume はこのファイルを仕様からの相対パスで読み込み、仕様が URL の場合はファイルを取得します。読み込めない $ref や、ドキュメント内を指す $ref（#/…）の場合、そのサンプルは除外され、BLUME_OPENAPI_CODE_SAMPLE_REF の警告が表示されます。

paths:
  /plants:
    get:
      x-codeSamples:
        - lang: go
          source:
            $ref: ./code_samples/go/list_plants.go

生成された API ドキュメントに SDK の例を追加するでは、TypeScript と Python の SDK を例にサンプルの追加手順を説明しています。SDK のリリースによって動かなくなったサンプルを検出するチェックも紹介しています。

Try it プレイグラウンド

ネイティブにレンダリングされたオペレーションページには、デフォルトでインタラクティブな Try it パネルが付属します。Blume はオペレーション自体からフォームを生成します。パス、クエリ、ヘッダーの各パラメーターに入力欄が用意され、リクエストボディのスキーマからボディエディターが構築され、すべてに仕様の例があらかじめ入力されます。値は仕様の記述どおりの形式で送信されます。配列やオブジェクトのパラメーターは style と explode に従い（クエリでは tags=dog&tags=cat、パスでは 1,2、deepObject では filter[color]=red）、application/x-www-form-urlencoded または multipart/form-data のボディは JSON ではなくフォームフィールドとして送信されます。サーバーピッカーにはオペレーションのサーバー（オペレーション自身の servers、なければパスの servers、それもなければ仕様の servers で、各 {variable} には default の値が使われます）が一覧表示され、それ以外のベース URL を入力できる自由入力欄もあります。認証の入力欄はオペレーションの解決されたセキュリティに対応します。ベアラートークン、API キー、Basic 認証の資格情報に対応し、OAuth2 はトークンを貼り付ける欄として表示されます（アクセストークンはご自身で用意してください。Blume は OAuth2 フローを実行しません）。

オペレーションのレスポンスのいずれかが JSON の場合、リクエストは JSON を要求します。Send とコードサンプルは、レスポンスに列挙された最初の JSON メディアタイプ（成功レスポンスのものが優先されます）を指定した Accept ヘッダーを送信します。Laravel などのフレームワークは、このヘッダーのないリクエストをブラウザから送信されたものとして扱い、認証されていない呼び出しに対して、API がドキュメントに記載している 401 を返す代わりにログインページへリダイレクトしてしまうためです。オペレーションが Accept ヘッダーパラメーターを宣言している場合は、そちらが代わりに使われます。

パネルとコードサンプルは常に連動します。フォームに入力した値は生成されるサンプルにリアルタイムで反映されるため、コピーした curl コマンドは常に Send が実行する内容と完全に一致します。また、パネルがページの負担になることもありません。パネルは折りたたまれた状態でサーバーレンダリングされ、その JavaScript は読者が初めてパネルを開いたときにのみ読み込まれます。パネルに一度も触れない読者は、その JavaScript を一切ダウンロードしません。

ブラウザから送信できない唯一のメソッドが TRACE です。fetch はこのメソッドを拒否するため、trace オペレーションでは Send はリクエストを送信せず、送信できない旨を表示します。また、（fetch をベースにした）JavaScript のサンプルはコードではなく注記として表示されます。cURL と Python のサンプルでは問題なく送信できます。

playground: false を指定するだけで、パネルを完全に無効化できます。

reference: [openapi({ 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 ルート（basePath を設定している場合は {basePath}/_api-proxy）が有効になります。ただし、これにはサーバー出力、つまり blume/deploy の deployment: vercel() のようなホストアダプターが必要です。

reference: [
  openapi({
    spec: "./openapi.yaml",
    playground: {
      proxy: true,   // or a URL of your own
    },
  }),
],

組み込みプロキシは、仕様の servers（ドキュメント、パス、オペレーションのいずれのレベルでも可。変数にはデフォルト値が使われます）で宣言されたオリジンにのみリクエストを転送します（リダイレクト先も同様です）。そのため、公開されたドキュメントのデプロイメントを悪用して、同じネットワーク上の他のホストにリクエストを送ることはできません。パネルに入力した Custom base URL は、仕様に記載されたサーバーとは見なされません。プロキシが有効な場合、そこへのリクエストは 403 で拒否されます。プロキシが転送するのは、パネル自身が設定したヘッダー（入力された資格情報とヘッダーパラメーター、Accept ヘッダー、およびボディの Content-Type）のみです。そのため、Cookie、ブラウザがドキュメントサイト向けに付与する資格情報（パスワードで保護されたプレビューでの HTTP Basic 認証など）、ホストが追加するヘッダー（X-Forwarded-For、CF-*、X-Vercel-*）が API に届くことはありません。プロキシが読み込むリクエストボディは 4 MB までです（それより大きい場合は 413 が返されます）。また、中継するすべてのレスポンスには Content-Security-Policy: sandbox、X-Content-Type-Options: nosniff、Cross-Origin-Resource-Policy: same-origin が付与され、HTML や SVG の場合はさらに Content-Disposition: attachment が付与されます。これにより、入力内容をそのまま返す API のエラーページがあっても、ドキュメントのオリジン上でスクリプトが実行されることはありません。また、読者が呼び出せる他のすべてのサーバールートと同様に、プロキシにも読者ごとのレート制限が適用されます。

Try it のリクエストがブロックされる場合は、API ドキュメントのプレイグラウンドで CORS エラーを解決するを参照してください。このガイドでは、問題を再現し、ブラウザが送信するプリフライトリクエストを確認したうえで、API 側の CORS ポリシーまたは組み込みプロキシを使って解決する方法を説明しています。

複数の仕様

1 つのアダプターから複数の仕様を公開するには、sources を使います。各ソースは独自の概要ルートとオペレーションページを持ち、アダプターの表示オプションを共有します。各ソースには label（サイドバーではグループ名として記述どおりに表示され、ルートの導出にも使われます）を指定するか、明示的な route を設定してください。

reference: [
  openapi({
    sources: [
      { label: "Public API", spec: "./public.json" },   // → /reference/public-api
      { label: "Admin API", route: "/admin", spec: "./admin.json" },
    ],
  }),
],

ソースのグループはそのルートに配置され、ルートの上位にある各フォルダーもサイドバーのグループになります。そのため、仕様のルートには、その仕様が説明するフォルダーを指定してください。route: "/apis/messaging" を指定すると、ソースのグループは messaging フォルダー自身のグループになり、label の名前で表示されます。一方、"/apis/messaging/openapi" を指定すると、そのグループは他に何も含まない Messaging グループの中にネストされます。

spec は単一エントリの sources の省略形です。そのため、sources を使うのは仕様が複数ある場合だけで十分です。2 つの仕様で異なる表示オプション（たとえば異なるコードサンプルのセット）が必要な場合は、代わりに 2 つの openapi() アダプターを、それぞれ独自の route を指定して列挙してください。ネイティブページと並べて埋め込む Scalar リファレンスは、リスト内の独立した scalar() アダプターとして扱います。ソースはリストの順序で解決され、2 つのソースが同じルートに解決された場合は最初のものが優先されます（除外されたソースについてはビルド時に警告が表示されます）。

複数の OpenAPI 仕様を 1 つのドキュメントサイトにまとめるでは、この方法で API ポータルを構築し、各サービスの仕様をそれぞれ独自のルートとタブに配置しています。

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

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

reference: [
  openapi({
    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.」）を続けたものになります。そのため、簡潔な 1 行のサマリーしかない仕様でも、ページごとに固有で、スニペットに適した長さのディスクリプションが付きます。この文は英語です。仕様の文章が別の言語で書かれているサイトでは、ソースに seoDescriptionSuffix: false を設定すると、この文が削除され、各ページのディスクリプションは仕様に記述された文章だけになります。description と summary のどちらもないオペレーションはタイトル（GET /pets）にフォールバックするため、ディスクリプションが空のページが公開されることはありません。

reference: [
  openapi({
    sources: [{ spec: "./openapi.de.json", seoDescriptionSuffix: false }],
  }),
],

scalar() の埋め込みでは、これらの設定のうち noindex のみを指定できます。埋め込みはもともと Blume の検索と llms.txt の対象外であるため、2 つの include* 設定は効果がありません。

オーバーレイ

仕様が別のツールで生成されている場合や別のチームが管理している場合は、OpenAPI Overlay を使うと、ドキュメント向けの変更を仕様本体に加えずに済みます。オーバーレイとは、仕様に加える変更（よりわかりやすい説明、公開用のサーバー URL、内部オペレーションの削除など）を列挙した別ファイルです。オーバーレイは spec と並べて列挙します。各オーバーレイにはローカルパスか http(s) URL を指定し、列挙した順に適用されます。

reference: [
  openapi({
    spec: "./openapi.json",
    overlays: ["./overlays/public.yaml"],
  }),
],

overlay: 1.1.0
info:
  title: Public docs
  version: 1.0.0
actions:
  - target: $.paths.*[?@['x-internal'] == true]
    remove: true
  - target: $.info
    update:
      description: The public Acme API.

各アクションの target は JSONPath 式です。update は選択したすべてのノードにマージされます。オブジェクトはキーごとにマージされ、配列には新しい項目が追加され、それ以外の値は置き換えられます。copy は仕様内の別の場所にあるノードをマージし（Overlay 1.1）、remove: true は対象を削除します。Overlay Specification 1.0 と 1.1 の両方に対応しています。

オーバーレイは、Blume が OpenAPI 3.1 にアップグレードする前の、記述されたままの仕様に適用されます。そのため、オーバーレイは仕様を記述したバージョンを対象にしてください。仕様から生成されるすべてのもの（オペレーションページ、サイドバー、検索、llms.txt、MCP サーバー）に結果が反映されます。sources を使う場合は、各ソースに独自の overlays を指定してください。適用できないオーバーレイがあると、読み込めない仕様の場合と同様にリファレンスがエラーになります。そのため、壊れたオーバーレイが原因で、隠すはずだった内容が公開されることはありません。

公開 API ドキュメントから内部エンドポイントを削除するでは、ビルドのたびに、生成された仕様から内部オペレーションを取り除くオーバーレイの作成手順を説明しています。

認可

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

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

• オペレーション自身の security は、ドキュメントのルートで指定されたデフォルトを上書きします。security: [] を指定したオペレーションは公開扱いとなり、Authorization セクションはレンダリングされません。
• 複数の要件エントリは選択肢を表し、「または」のグループとしてレンダリングされます。1 つのエントリ内のすべてのスキームは同時に必要です。コードサンプルには最初の選択肢が使われます。
• 空の {} エントリは、そのオペレーションで認証が任意であることを意味し、セクションにもその旨が表示されます。
• OAuth2 のスコープはスキームごとに一覧表示されます。components.securitySchemes に記述されたスキームの description はインラインでレンダリングされます。

Webhook とコールバック

API が送信するリクエストもドキュメント化されます。仕様のトップレベルの webhooks にある各 Webhook には、オペレーションと同様に独自のページが作られます。ページは最初のタグの下に配置され、タグがない場合は Webhooks グループに配置されます。このページには、ペイロードのスキーマと、受信側のエンドポイントが返すべきレスポンスが表示されます。このリクエストは API が受け付けるものではなく API が送信するものなので、サイドのレールには Try it パネルとコードサンプルの代わりにペイロードの例が表示されます。Webhook ページには、その Webhook 自身が宣言した security のみが表示されます。仕様のルートの security は API への呼び出しを保護するものであり、API が送信するリクエストには適用されないためです。共有パスアイテムへの $ref になっている Webhook は除外され、BLUME_OPENAPI_REF_PATH_ITEM の警告が表示されます。

webhooks:
  newPet:
    post:
      summary: New pet added
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Pet"
      responses:
        "200":
          description: Return a 200 to acknowledge the event.

3.0 の仕様で x-webhooks 拡張の下に記述された Webhook は、Blume が仕様を 3.1 にアップグレードする際に webhooks に変換されます。すでに 3.1 以降の仕様はアップグレードされないため、x-webhooks の下に残っている Webhook は何もレンダリングされず、BLUME_OPENAPI_X_WEBHOOKS の警告が表示されます。フィールド名を webhooks に変更してください。

オペレーションの callbacks（呼び出し元が指定した URL に対して API が送り返すリクエスト）は、そのオペレーションのページの Callbacks セクションにレンダリングされます。各コールバックには、URL 式（{$request.body#/callbackUrl}）、メソッド、パラメーター（署名ヘッダーなど）、リクエストボディ、想定されるレスポンスが表示されます。components.callbacks の下で宣言し、$ref で参照したコールバックも同じように扱われます。

Webhook ページも本物のページです。検索、llms.txt、MCP サーバーに含まれます。また、その Markdown ではこれが API から送信されるリクエストであることがエージェントに伝えられるため、エージェントがそれを呼び出そうとすることはありません。

OpenAPI 3.1 で Webhook のドキュメントを作成するでは、Webhook ページに署名ヘッダーと受信確認のレスポンスを追加し、さらに実際に動作する Node.js の受信側実装を含む受信ガイドを作成します。

仕様の警告

Blume は、OpenAPI スキーマに照らした仕様の検証は行いません。検証には、CI で Spectral や oasdiff などのリンターを実行してください。ただし、blume dev、blume build、blume check では、そのままでは何の兆候もなく誤ってレンダリングされてしまうミスや、仕様のうち除外される部分について警告が表示されます。各警告には対象の仕様が示され、リファレンスの残りの部分は通常どおりビルドされます。

CI で API ドキュメントをバックエンドの変更と同期させるでは、これらのチェックを GitHub Actions で実行します。バックエンドから仕様をエクスポートし、仕様が古い場合、無効な場合、または破壊的変更を含む場合は失敗させたうえで、その仕様からリファレンスを再ビルドします。

独自のページにオペレーションを表示する

どの MDX ページでも、<Operation> を使ってリファレンスのオペレーションを表示できます。オペレーション自身のページと同じように、認可、パラメーター、リクエストボディ、レスポンスが、Try it パネルやコードサンプルと並んで表示されます。そのため、クイックスタートでは、読者を別のページに移動させることなく、扱う呼び出しを順を追って説明できます。

---
title: Quickstart
mode: wide
---

Create your first pet:

<Operation source="reference" id="add-pet" />

source はリファレンスをそのルートで指定します。スラッシュを除き、小文字に変換してハイフンで区切った形式です（/reference は reference、/api/v2 は api-v2）。id はオペレーションを指定します。operationId を小文字に変換して単語をハイフンで区切ったもの（addPet は add-pet）か、operationId がない場合はメソッドとパス（post-pets）です。両方を最も確実に取得する方法は、オペレーションページの生の MDX 版を参照することです。これはページの URL に .mdx を付けた場所にあり、その本文がそのままコピーすべきタグになっています。オペレーションは 2 カラムでレイアウトされるため、ページには mode: wide を指定してください。目次と並べると左カラムが狭くなってしまいます。ページの Markdown 版では、このタグはオペレーション自身のページと同様に、エンドポイント、リクエストボディ、レスポンスに置き換えられます。

代わりに Scalar を埋め込む

openapi() は常に Blume 独自のページをレンダリングします。代わりに Scalar の自己完結型 API リファレンス UI（独自のサイドバー、検索、テーマ、リクエストクライアントを備えています）を単一のルートに埋め込むには、このアダプターの代わりに（または並べて）blume/reference の scalar() アダプターを列挙してください。埋め込みでできることとできないこと、および Scalar 独自のオプションを渡す方法については、Scalar のページで説明しています。