createGraphQL()
GraphQL サーバーのインスタンスです。
GraphQL Server
Fumadocs GraphQL のメインとなる設定です。
ブラウザ環境から参照しないでください。
input
読み込む GraphQL スキーマです。次のいずれかを指定します。
- SDL ファイルのパス/URL の配列。
- スキーマ ID -> 入力 のレコード。
レコード形式の入力には、SDL ファイルのパス/URL、SDL テキスト、イントロスペクション結果、GraphQLSchema インスタンス、またはそれらを返す関数を指定できます。
読み込めるのはここに列挙したスキーマのみです。それ以外の ID を getSchema() に渡すとエラーがスローされます。
import { createGraphQL } from '@fumadocs/graphql/server';
export const graphql = createGraphQL({
input: ['./schema.graphql'],
});SDL ファイルの配列を渡すと、それらを 1 つのスキーマにマージできます。型の拡張 (例: extend type Query) にも対応しています。
import { createGraphQL } from '@fumadocs/graphql/server';
export const graphql = createGraphQL({
input: {
api: ['./base.graphql', './orders.graphql'],
},
});examples
GraphQL ドキュメントから読み込むオペレーションの例です。ファイルパス、URL、または GraphQL テキストを指定できます。
import { createGraphQL } from '@fumadocs/graphql/server';
export const graphql = createGraphQL({
input: ['./schema.graphql'],
examples: ['./examples.graphql'],
});配列を指定すると、すべてのスキーマに適用されます。名前付きの各オペレーションは、そのオペレーションが選択するルートフィールドのページに例として表示され、自動生成された例の代わりに使用されます。
# 顧客の公開プロフィールです。
query CustomerProfile($id: ID! = "cus_42") {
customer(id: $id) {
id
name
}
}| 例 | 取得元 |
|---|---|
| title | オペレーション名(例: CustomerProfile の場合は Customer Profile) |
| description | オペレーションの """ による説明、またはその直上にある # コメント(Markdown 形式) |
| variables | 変数のデフォルト値(クエリからは除外されます)、または必須の変数に対して自動生成された値 |
| response | 選択セットから生成 |
各オペレーションは一意の名前を持ち、スキーマに対して有効である必要があります。満たさない場合はビルドが失敗します。
プレイグラウンドで編集できるように、ルートフィールドの引数は customer(id: $id) のように、同名の変数で指定する必要があります。
disableCache
読み込んだスキーマとサンプルのキャッシュを無効にします。開発中など、スキーマやサンプルを頻繁に変更する場合に便利です。
import { createGraphQL } from '@fumadocs/graphql/server';
export const graphql = createGraphQL({
input: ['./schema.graphql'],
disableCache: true,
});スキーマを一度だけ読み込む
ページは props でスキーマ全体を受け取るため、ページの読み込み、ナビゲーション、プリフェッチのたびにスキーマが再送信されます。スキーマが大きい場合は、props から除外してください。
import { createGraphQL } from '@fumadocs/graphql/server';
export const graphql = createGraphQL({
// ID は URL に含まれるため、URL セーフな値にしてください
input: { store: './store.graphql' },
includeSchema: false,
});loadSchema を渡すと、各スキーマの SDL をブラウザセッションごとに1回だけ読み込みます。この処理はサーバーレンダリング時にも実行されます。
'use client';
import { preload } from 'react-dom';
import { createGraphQLPage } from '@fumadocs/graphql/ui';
export const GraphQLPage = createGraphQLPage({
async loadSchema(id) {
if (typeof window === 'undefined') {
// ブラウザがページと同時にダウンロードを開始します
preload(`/api/graphql-schema/${id}`, { as: 'fetch', crossOrigin: 'anonymous' });
const { graphql } = await import('@/lib/graphql');
return (await graphql.getSchema(id)).sdl;
}
return (await fetch(`/api/graphql-schema/${id}`)).text();
},
});ルートを用意して、スキーマをブラウザに配信します。
import { graphql } from '@/lib/graphql';
export async function GET(_req: Request, { params }: RouteContext<'/api/graphql-schema/[id]'>) {
return new Response((await graphql.getSchema((await params).id)).sdl);
}
// 静的エクスポート用
export async function generateStaticParams() {
return Object.keys(await graphql.getSchemas()).map((id) => ({ id }));
}- Fumadocs CLI でインストールした UI では、
createGraphQLRenderer()にloadSchemaを渡してください。 - ブラウザは各スキーマをリロードするまで保持します。
disableCacheを使う場合は、includeSchemaを有効のままにしておいてください。
ページの生成
staticSource() と dynamicSource() は、loader() で使用するページを生成します。どちらも同じオプションを受け付けます。
export const source = loader(
{
docs: docs.toFumadocsSource(),
graphql: await graphql.staticSource({
baseDir: 'graphql',
}),
},
// ...
);per
ページの内容をカスタマイズします。デフォルトは item です。
| モード | 内容 | ファイルパス |
|---|---|---|
| item | オペレーションごと (includeTypes を指定した場合は名前付き型ごとにも生成) | {name}.mdx |
| file | スキーマ内のオペレーション、および includeTypes を指定した場合はその名前付き型 | {file_name}.mdx |
| custom | 下記を参照 | N/A |
custom に設定すると、関数を渡して生成プロセスを完全にカスタマイズできます。
import { graphql } from '@/lib/graphql';
await graphql.staticSource({
per: 'custom',
toPages(builder) {
builder.create({
type: 'operation',
path: 'my-orders.mdx',
info: { title: 'My Orders' },
item: { kind: 'query', name: 'orders' },
});
},
});groupBy
per: 'item' の場合に、生成されたページをフォルダーにまとめる方法をカスタマイズします。デフォルトは kind です。
| モード | フォルダー |
|---|---|
| kind | 種類ごとに分類 (例: queries/、mutations/) |
| none | フォルダーを作成しない |
エントリーのグループ名を返す関数を渡すこともできます。
import { graphql } from '@/lib/graphql';
await graphql.staticSource({
groupBy: (entry) => (entry.type === 'operation' ? 'operations' : 'types'),
});includeOperations & includeTypes
ドキュメント化するオペレーション(クエリ/ミューテーション/サブスクリプションのフィールド)と名前付き型を絞り込みます。
includeOperations:per: 'item'の場合、オペレーションごとに1ページを生成します。デフォルトはtrueです。includeTypes: 名前付き型を対象にします。per: 'item'の場合は型ごとに個別のページを生成し、per: 'file'の場合は同じページ内に出力します。デフォルトはfalseです。どちらの場合でも、オペレーションのページには使用している型が表示されます。
型のページには、その型が使用されている箇所が表示されます。また、型のページ同士や、型のページとオペレーションのページは相互にリンクされます。
import { graphql } from '@/lib/graphql';
await graphql.staticSource({
// サブスクリプションは除外
includeOperations: (kind, field) => kind !== 'subscription',
// 内部の型以外をドキュメント化
includeTypes: (type) => !type.name.startsWith('Internal'),
});name & slugify
生成されるページのファイル名をカスタマイズします。
GraphQL の名前はもともと URL セーフなため、デフォルトでは元の名前が大文字・小文字も含めてそのまま使用されます。
import { graphql } from '@/lib/graphql';
await graphql.staticSource({
per: 'item',
name: (entry) => entry.item.name.toLowerCase(),
});slugify は、グループ名(およびデフォルトではアイテム名)を URL で使用できる形式のセグメントに変換します。
meta
ページツリーをカスタマイズするための meta.json ファイルを生成します。デフォルトでは無効です。
folderStyle | ページツリー |
|---|---|
| folder | グループごとにフォルダーを1つ作成(デフォルト) |
| separator | グループごとに区切りを1つ置き、その下にページを配置 |
import { graphql } from '@/lib/graphql';
await graphql.staticSource({
meta: { folderStyle: 'separator' },
});LLM向けのMarkdown
page.data.getText() は、ページの項目をMarkdown形式で返します。オペレーションにはシグネチャ、引数、例、使用している型のSDLが、名前付き型にはそのSDLと使用箇所が含まれます。たとえば、docsLlms では次のように使用します。
import { llms } from 'fumadocs-core/source';
import { source } from '@/lib/source';
export const docsLlms = llms(source, {
renderPage: async (page) => {
if (page.type === 'graphql') {
return `# ${page.data.title}\n\n${await page.data.getText('processed')}`;
}
// 以下は既存の処理...
},
});ローダープラグイン
loaderPlugin() は、ページツリー内の GraphQL ページに次の装飾を加えます。
- 各オペレーションページに
query/mutation/subscriptionのバッジを付けます。 - 非推奨のオペレーションに取り消し線を付けます。
export const source = loader(
// ...
{
baseUrl: '/docs',
plugins: [graphql.loaderPlugin()],
},
);How is this guide?
最終更新日
General Translation
Ferry Health
assistant-ui
Inkeep