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,
});loadDocument を渡すと、各ドキュメントがブラウザセッションごとに1回だけ読み込まれるようになります。この関数はサーバーレンダリング時にも実行されます。
'use client';
import { preload } from 'react-dom';
import { createOpenAPIPage } from 'fumadocs-openapi/ui';
export const OpenAPIPage = createOpenAPIPage({
async loadDocument(id) {
if (import.meta.env.SSR) {
// ブラウザがページと同時にダウンロードを開始する
preload(`/api/openapi/${id}`, { as: 'fetch', crossOrigin: 'anonymous' });
const { openapi } = await import('@/lib/openapi');
return (await openapi.getSchema(id)).bundled;
}
return (await fetch(`/api/openapi/${id}`)).json();
},
});ルートを用意して、ドキュメントをブラウザに配信します。
import type { ApiContext } from 'waku/router';
import { openapi } from '@/lib/openapi';
export async function GET(_: Request, { params }: ApiContext<'/api/openapi/[id]'>) {
return Response.json((await openapi.getSchema(params.id)).bundled);
}loadDocumentは生成された MDX ファイルでも使用できます。- Fumadocs CLI でインストールした UI では、
loadDocumentをcreateOpenAPIRenderer()に渡してください。 - ブラウザは各ドキュメントをリロードまで保持します。
disableCacheを使用する場合は、includeDocumentを有効のままにしてください。
プロキシの作成
プロキシサーバーを使うと、ブラウザの CORS 制限を受けずに HTTP リクエストを送信できます。API プレイグラウンドでは、次の用途でプロキシを使用します。
- CORS でオリジンが許可されていない API エンドポイントへのリクエスト
- コンフィデンシャルクライアント(クライアントシークレットを持つクライアント)による OAuth リクエストおよびデバイスフロー
プロキシは認証なしで公開されます。リクエストのヘッダーとボディは、Authorization を含めてそのまま転送されます。allowedOrigins と filterRequest でアクセスを制限してください。
セットアップ
プレイグラウンドは、オペレーションのメソッドを URL に含めたうえで、リクエストを POST としてプロキシに送信します。このためのルートハンドラーを作成してください。
import { openapi } from '@/lib/openapi';
export const { POST } = openapi.createProxy();次に、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';
export const GET = openapi.createOAuthHandler();このルートの 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';
export const GET = openapi.createOAuthHandler({ inline: true });
export async function getConfig() {
return { render: 'static' } as const;
}リダイレクト URI には、oauthRedirectUrl: '/api/oauth.html' のように .html の URL を指定してください。スクリプトはページ内に埋め込まれるため、このルートに適用される Content Security Policy でインラインスクリプトを許可する必要があります。
How is this guide?
