コンテンツにスキップ
Blume
Esc
↑↓移動↵開く⌘Jプレビュー
このページの内容

GraphQL

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

Blume に GraphQL スキーマを指定すると、ネイティブな API リファレンスが生成されます。クエリ、ミューテーション、サブスクリプションのルートフィールドごとに実際のページが 1 つずつ作成されます。さらに、オブジェクト、入力オブジェクト、列挙型、インターフェース、ユニオン、カスタムスカラーの名前付き型ごとにもページが 1 つずつ作成されます。各ページには、引数、デフォルト値、非推奨情報、使用箇所へのバックリンクが表示されます。生成されたオペレーション例、コードサンプル、インタラクティブな Try it パネルも表示されます。各ページは正真正銘の Blume ページなので、それぞれ独自の URL を持ちます。サイト検索や llms.txt にも表示され、Open Graph 画像も生成されます。この点は手書きのドキュメントとまったく同じです。

リファレンスを生成するのは blume/reference の graphql() アダプターです。reference の下に、OpenAPI や AsyncAPI のアダプターと並べて記述します：

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

export default defineConfig({
  reference: [
    graphql({
      spec: "./schema.graphql",
      endpoint: "https://api.example.com/graphql",
    }),
  ],
});

これにより、リファレンスが /graphql（概要ページ）にマウントされます。ルートフィールドは /graphql/queries/<field>、/graphql/mutations/<field>、/graphql/subscriptions/<field> に配置されます。型は種類ごとにグループ化され、/graphql/objects/<type> や /graphql/enums/<type> などに配置されます。

spec には、プロジェクト内のローカルファイルへのパスか http(s) URL を指定します。次の 2 つの形式に対応しています：

  • SDL テキスト — 型定義を含む .graphql ファイルです。ファイル内で宣言せずに使用しているディレクティブ（Apollo Federation の @key や AppSync の @aws_* など）は無視されます。
  • イントロスペクション結果 — 標準のイントロスペクションクエリを実行して得られる JSON です。生の { "__schema": … } 形式と、完全なレスポンスエンベロープである { "data": { "__schema": … } } 形式のどちらにも対応しています。

endpoint には、実際に稼働している GraphQL API の URL を指定します。OpenAPI ドキュメントとは異なり、スキーマにはサーバーが記述されていません。そのため、Try it パネルと生成されるコードサンプルはこのエンドポイントに送信されます。省略した場合、サンプルにはプレースホルダー URL が表示されるので、読者が自分で置き換えます。

リファレンスは、それ自体ではヘッダータブを追加しません。表示するには、ナビゲーションタブのパスをリファレンスのルートに設定してください。これにより、リファレンスのサイドバーの表示範囲も設定されます：

navigation: {
  tabs: [{ label: "GraphQL", path: "/graphql" }],
}

スキーマから GraphQL ドキュメントを生成するガイドでは、スキーマからサイトをデプロイするまでの手順を順を追って説明しています。完成したサイトには、サンドボックスにクエリを送信する Try it パネルも備わっています。

生成される例

すべてのオペレーションページには、完全で有効なオペレーション例が含まれます。この例では、引数ごとにスキーマに基づいて型付けされた変数が 1 つずつ定義されます。また、戻り値の型に対しては、深さを制限した選択セットが付きます。これに対応する変数の例と、同じ選択セットを反映したレスポンスの例も含まれます。引数にデフォルト値が宣言されている場合、その変数の初期値はそのデフォルト値になります。また、選択セットには非推奨のフィールドは含まれません。コードサンプルには、設定した各言語で実際の HTTP リクエスト（{ query, variables } の JSON POST）がそのまま表示されます。openapi() と同じ言語を使用でき、codeSamples: false を指定するとコードサンプルは表示されません：

reference: [
  graphql({
    spec: "./schema.graphql",
    codeSamples: ["curl", "js"],   // any language openapi() offers
  }),
],

Blume がサンプルを生成できない ID を指定した場合、その ID は除外され、BLUME_GRAPHQL_UNKNOWN_CODE_SAMPLE 警告が表示されます。この警告には、サンプルを生成できる ID の一覧が示されます。

型ページ

名前付き型には、ディープリンクが可能な専用ページが用意され、サイドバーでは種類ごとにグループ化されます。各ページには、フィールドと入力フィールド（型へのリンク付き）、列挙値、ユニオンのメンバー、インターフェースの実装が表示されます。さらに、Used by セクション（その型を返す・受け取るオペレーションと、その型を参照する他の型の一覧）も表示されます。仕様で定義されたスカラー（String、Int など）にはページが作成されません。カスタムスカラーにはページが作成され、specifiedBy の URL も表示されます。

複数のスキーマ

sources の各エントリは、1 つのスキーマをそれぞれ独自のルートにレンダリングします。ソースごとに endpoint を指定すると、アダプターの endpoint よりも優先されます：

reference: [
  graphql({
    endpoint: "https://api.example.com/graphql",
    sources: [
      { label: "Public API", spec: "./schema.graphql" },
      {
        label: "Admin API",
        route: "/graphql-admin",
        spec: "./admin.graphql",
        endpoint: "https://admin.example.com/graphql",
      },
    ],
  }),
],

spec は、エントリが 1 つだけの sources の省略形です。表示オプションを変えたいスキーマは、別々の graphql() アダプターに分け、それぞれに独自の route を指定します。各ソースでは、openapi() と同じソースごとの制御を使用できます。使用できるのは includeInSearch、includeInLlms、noindex、seoDescriptionSuffix です。GraphQL の場合、生成される文にはクエリ、ミューテーション、または型の名前が入ります（例：「Reference for the pets query in the GraphQL API.」）。

Try it プレイグラウンド

クエリとミューテーションのページには、インタラクティブなパネルが表示されます。このパネルでは、リクエストボディ（クエリと変数）を編集できます。送信先にはエンドポイントかカスタム URL を指定して、そのまま送信できます。コードサンプルはリアルタイムで更新されるため、コピーした内容は実際に送信した内容とバイト単位で一致します。パネルを無効にするには、playground: false を指定します。サブスクリプションのページには、パネルの代わりに、生成されたオペレーションとイベントの例が表示されます。サブスクリプションはステートフルなトランスポート（WebSocket または SSE）上で動作するため、プレイグラウンドの単一の HTTP POST では扱えません。

スキーマには API の認証方法が記述されていません。そのため、auth を指定するまで、パネルは認証情報を送信しません。auth の形式は、手書きのエンドポイントページで使用する api.auth と同じです。method には bearer、basic、key（ヘッダーで渡す API キー）、none のいずれかを指定します。name には API キーを入れるヘッダーを指定します（デフォルトは x-api-key）。指定すると、すべてのオペレーションページに Authorization セクションが追加されます。また、パネルには OpenAPI のものと同じように動作する認証情報フィールドが追加され、コードサンプルにはプレースホルダーの認証情報が表示されます。ソースごとに auth を指定すると、アダプターの auth よりも優先されます：

reference: [
  graphql({
    spec: "./schema.graphql",
    endpoint: "https://api.example.com/graphql",
    auth: { method: "bearer" },
  }),
],

GraphQL API がドキュメントサイトからのクロスオリジンリクエストを許可していない場合は、CORS プロキシを経由して送信してください。独自のプロキシの URL を指定するか、true を指定して組み込みの /_api-proxy エンドポイント（basePath を設定している場合はその配下）を使用します。組み込みのプロキシを使うにはサーバー出力が必要です。具体的には、blume/deploy の deployment: vercel() のようなホストアダプターを設定します。組み込みのプロキシは、ドキュメント化された仕様で宣言されているオリジンにのみ転送します。転送先は、設定された各 GraphQL の endpoint と、ドキュメント化された OpenAPI 仕様に記述された絶対 URL の servers[].url です。そのため、公開されたドキュメントのデプロイを悪用して、他のホストにリクエストを送ることはできません。つまり、プロキシを動作させるには endpoint の指定が必須です。指定しない場合、このリファレンスで許可されるオリジンがないため、プロキシはすべての送信を拒否します（この場合、ビルド時に警告が表示されます）。リクエストボディのサイズ制限、ヘッダーの転送ルール、レスポンスヘッダーは、OpenAPI のプロキシと同じものが適用されます。

reference: [
  graphql({
    spec: "./schema.graphql",
    endpoint: "https://api.example.com/graphql",
    playground: { proxy: true },
  }),
],

GraphQL には、Scalar を使った代替手段はありません。scalar() の埋め込みが読み込めるのは OpenAPI と AsyncAPI のドキュメントだけです。そのため、GraphQL リファレンスは常にネイティブでレンダリングされます。

最終更新

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