createOpenAPI()

OpenAPI Serverアンカーリンクをコピー

Fumadocs OpenAPI のメイン設定です。

inputアンカーリンクをコピー

読み込む OpenAPI スキーマです。

• ファイルパス
• 外部 URL
• 関数 (後述)

読み込めるのはここに指定したスキーマのみです。それ以外の ID を getSchema() に渡したり、ページでプリロードしたりするとエラーがスローされます。

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 { Route } from './+types/openapi';
import { openapi } from '@/lib/openapi';

export async function loader({ params }: Route.LoaderArgs) {
  return Response.json((await openapi.getSchema(params.id)).bundled);
}

• loadDocument は生成された MDX ファイルでも使用できます。
• Fumadocs CLI でインストールした UI では、loadDocument を createOpenAPIRenderer() に渡してください。
• ブラウザは各ドキュメントをリロードまで保持します。disableCache を使用する場合は、includeDocument を有効にしたままにしてください。

プロキシの作成アンカーリンクをコピー

プロキシサーバーは、ブラウザの CORS 制限を受けずに HTTP リクエストを送信します。API プレイグラウンドでは、次の用途でプロキシを使用します。

• CORS で自分のオリジンが許可されていない API エンドポイントへのリクエスト。
• コンフィデンシャルクライアント (クライアントシークレットを使用) の OAuth リクエストおよびデバイスフロー。

セットアップアンカーリンクをコピー

プロキシ用のルートハンドラーを作成します。

import type { Route } from './+types/proxy';
import { openapi } from '@/lib/openapi';

const proxy = openapi.createProxy();

export const loader = ({ request }: Route.LoaderArgs) => proxy.handle(request);
export const action = ({ request }: Route.ActionArgs) => 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'],
});

リダイレクト先も同じルールでチェックされます。

リクエストを拒否するには filterRequest を使用します。たとえば、読み取りのみを許可するには次のようにします。

openapi.createProxy({
  // false を返したリクエストはプロキシされずに拒否されます
  filterRequest: (request) => request.method === 'GET',
});

OAuth リダイレクトアンカーリンクをコピー

OAuth プロバイダーは登録済みのリダイレクト URI しか受け付けませんが、API プレイグラウンドはデフォルトで現在のページにリダイレクトします。 そこで、全ページ共通のリダイレクト URI となるルートハンドラーを作成してください。このハンドラーは、フローを開始したページへユーザーを戻します。

import type { Route } from './+types/oauth';
import { openapi } from '@/lib/openapi';

const handler = openapi.createOAuthHandler();

export const loader = ({ request }: Route.LoaderArgs) => handler(request);

このルートの URL を createOpenAPIPage() に渡し、完全な URL(例: https://docs.example.com/api/oauth)を OAuth プロバイダーに登録してください。

export const OpenAPIPage = createOpenAPIPage({
  oauthRedirectUrl: '/api/oauth', 
});

静的サイトアンカーリンクをコピー

静的サイトでは、ルートはファイルとしてプリレンダリングされます。inline: true を渡してスクリプトをページ内に埋め込み、静的ホストがファイルを HTML として配信できるよう、パスの末尾を .html にしてください。

import type { Route } from './+types/oauth';
import { openapi } from '@/lib/openapi';

const handler = openapi.createOAuthHandler({ inline: true });

export const loader = ({ request }: Route.LoaderArgs) => handler(request);

oauthRedirectUrl: '/api/oauth.html' のように、.html の URL をリダイレクト URI として指定してください。スクリプトがページ内に埋め込まれるため、このルートに適用される Content Security Policy でインラインスクリプトを許可する必要があります。