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

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

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

ローカルの仕様

相対パスはプロジェクトルートから解決され、ビルド時に読み込まれます。JSON と YAML のどちらも使えます。

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

ルート

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

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

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

codeSamples は、オペレーションごとにレンダリングする言語を選択します（組み込み: curl、js、python）。expandSchemas を指定すると、ネストされたスキーマ行が折りたたまれた状態ではなく、展開された状態で表示されます。

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

Try it プレイグラウンド

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

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

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 ルートが有効になります。ただし、これにはサーバー出力、つまり blume/deploy の deployment: vercel() のようなホストアダプターが必要です。

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

組み込みプロキシは、仕様の servers で宣言されたオリジンにのみリクエストを転送します（リダイレクト先も同様です）。そのため、公開されたドキュメントのデプロイメントを悪用して、同じネットワーク上の他のホストにリクエストを送ることはできません。パネルに入力した Custom base URL は、仕様に記載されたサーバーとは見なされません。プロキシが有効な場合、そこへのリクエストは 403 で拒否されます。プロキシが読み込むリクエストボディは 4 MB までです（それより大きい場合は 413 が返されます）。また、中継するすべてのレスポンスには Content-Security-Policy: sandbox、X-Content-Type-Options: nosniff、Cross-Origin-Resource-Policy: same-origin が付与され、HTML や SVG の場合はさらに Content-Disposition: attachment が付与されます。これにより、入力内容をそのまま返す API のエラーページがあっても、ドキュメントのオリジン上でスクリプトが実行されることはありません。

複数の仕様

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

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

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

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

生成されたページは、デフォルトで検索、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* 設定は効果がありません。

認可

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

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

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

代わりに Scalar を埋め込む

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