createOpenAPI()
OpenAPI のサーバーインスタンスです。
OpenAPI Server
Fumadocs OpenAPI のメインとなる設定です。
ブラウザ環境からは参照しないでください。
input
読み込み元となるOpenAPIスキーマです。
- ファイルパス
- 外部URL
- 関数(後述)
読み込めるのはここに指定したスキーマのみです。それ以外のIDを getSchema() に渡したり、ページでプリロードしたりするとエラーがスローされます。
信頼できないスキーマを input に渡さないでください。スキーマ内の $ref によってローカルファイルが読み取られたり、プライベートホストを含む任意のURLへフェッチされたりする可能性があります。
import { createOpenAPI } from 'fumadocs-openapi/server';
export const openapi = createOpenAPI({
input: ['./unkey.json'],
});ドキュメントを一度だけ読み込む
ページは props でドキュメント全体を受け取るため、ページの読み込み、ナビゲーション、プリフェッチのたびにドキュメントが再送信されます。ドキュメントが大きい場合は、props から除外してください。
import { createOpenAPI } from 'fumadocs-openapi/server';
export const openapi = createOpenAPI({
// ID は URL に含まれるため、URL セーフな値にしてください
input: { museum: './museum.yaml' },
includeDocument: false,
});TanStack Start のルートローダーはサーバーとブラウザの両方で実行されるため、docs ルートでは loadDocument を使わずにドキュメントを読み込めます。ブラウザがまだドキュメントを持っていない場合にのみ、サーバー関数を呼び出してください。
import { createServerFn } from '@tanstack/react-start';
import type { Document } from 'fumadocs-openapi';
import { openapi } from '@/lib/openapi';
// ブラウザが読み込み済みのドキュメント
const documents = new Map<string, Document>();
const getDocument = createServerFn({ method: 'GET' })
.validator((id: string) => id)
.handler(async ({ data: id }) => (await openapi.getSchema(id)).bundled);
export const Route = createFileRoute('/docs/$')({
component: Page,
loader: async ({ params }) => {
const data = await serverLoader({ data: params._splat?.split('/') ?? [] });
if (data.type === 'openapi') {
const { document: id, payload } = data.props;
payload.bundled = documents.get(id) ?? (await getDocument({ data: id }));
}
return data;
},
});
function Page() {
const page = useFumadocsLoader(Route.useLoaderData());
// 最初のページのドキュメントも保持する
if (page.type === 'openapi' && typeof window !== 'undefined')
documents.set(page.props.document, page.props.payload.bundled!);
// ...
}- 生成された MDX ファイルを使用する場合は、代わりにドキュメントを
preloaded.docsに配置してください。 - ブラウザは各ドキュメントをリロードまで保持します。
disableCacheを使用する場合は、includeDocumentを有効のままにしてください。
プロキシの作成
プロキシサーバーを使うと、ブラウザの CORS 制限を受けずに HTTP リクエストを送信できます。API プレイグラウンドでは、次の用途でプロキシを使用します。
- CORS でオリジンが許可されていない API エンドポイントへのリクエスト
- コンフィデンシャルクライアント(クライアントシークレットを持つクライアント)による OAuth リクエストおよびデバイスフロー
プロキシは認証なしで公開されます。リクエストのヘッダーとボディは、Authorization を含めてそのまま転送されます。allowedOrigins と filterRequest でアクセスを制限してください。
セットアップ
プレイグラウンドは、オペレーションのメソッドを URL に含めたうえで、リクエストを POST としてプロキシに送信します。このためのルートハンドラーを作成してください。
import { openapi } from '@/lib/openapi';
import { createFileRoute } from '@tanstack/react-router';
const proxy = openapi.createProxy();
export const Route = createFileRoute('/api/proxy')({
server: {
handlers: {
POST: ({ request }) => proxy.handle(request),
},
},
});次に、createOpenAPI() でこのルートの URL を指定します。
import { createOpenAPI } from 'fumadocs-openapi/server';
export const openapi = createOpenAPI({
proxyUrl: '/api/proxy',
});許可するオリジン
デフォルトでは、プロキシはすべてのパブリックなオリジンを受け入れますが、プライベートネットワーク上のホスト (例: localhost) は拒否し、サイトの Cookie も転送しません。
プロキシを制限したい場合や、プライベートな API をプロキシしたい場合は、プロキシルートで許可するオリジンを指定してください。
openapi.createProxy({
// 文字列または正規表現
allowedOrigins: ['https://api.example.com', 'http://localhost:8080'],
});リダイレクト先も同じルールでチェックされます。
プライベートネットワークへのリクエストの拒否には、Node.js または Deno が必要です。Bun などのその他のランタイムでは、
allowedOrigins を指定してください。
リクエストを拒否するには filterRequest を使用します。たとえば、読み取りのみを許可するには次のようにします。
openapi.createProxy({
// false が返されたプロキシ対象のリクエストは拒否されます
filterRequest: (request) => request.method === 'GET',
});OAuth リダイレクト
OAuth プロバイダーは登録済みのリダイレクト URI しか受け付けませんが、API プレイグラウンドはデフォルトで現在のページにリダイレクトします。 すべてのページで共通のリダイレクト URI として使うルートハンドラーを作成してください。このハンドラーが、フローを開始したページへユーザーを戻します。
import { openapi } from '@/lib/openapi';
import { createFileRoute } from '@tanstack/react-router';
const handler = openapi.createOAuthHandler();
export const Route = createFileRoute('/api/oauth')({
server: {
handlers: {
GET: async ({ request }) => handler(request),
},
},
});このルートの URL を createOpenAPIPage() に渡し、完全な URL(例: https://docs.example.com/api/oauth)を OAuth プロバイダーに登録してください。
export const OpenAPIPage = createOpenAPIPage({
oauthRedirectUrl: '/api/oauth',
});Content Security Policy(CSP)
ハンドラーは、自身のルートから配信されるスクリプトを使ってユーザーを元のページに戻します。そのルートに Content Security Policy が適用される場合は、'self' のスクリプトを許可する必要があります。'strict-dynamic' を含むポリシーでは 'self' が無視されるため、その場合はルートをポリシーの対象から除外してください。
静的サイト
静的サイトでは、ルートはファイルとして事前レンダリングされます。inline: true を渡してスクリプトをページ内に埋め込み、静的ホストがファイルを HTML として配信できるよう、パスの末尾を .html にしてください。
import { openapi } from '@/lib/openapi';
import { createFileRoute } from '@tanstack/react-router';
const handler = openapi.createOAuthHandler({ inline: true });
export const Route = createFileRoute('/api/oauth.html')({
server: {
handlers: {
GET: async ({ request }) => handler(request),
},
},
});リダイレクト URI には、oauthRedirectUrl: '/api/oauth.html' のように .html の URL を指定してください。スクリプトはページ内に埋め込まれるため、このルートに適用される Content Security Policy でインラインスクリプトを許可する必要があります。
How is this guide?
