OpenAPI

セットアップ

必要なパッケージをインストールします。

npm i fumadocs-openapi shiki

スタイルの生成

次の行を追加します。

Tailwind CSS

@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';
@import 'fumadocs-openapi/css/preset.css';

プラグインの設定

OpenAPI サーバーインスタンスと <OpenAPIPage /> コンポーネントを作成します。

import { createOpenAPI } from 'fumadocs-openapi/server';

// 注: これはサーバーサイドの API です
export const openapi = createOpenAPI({
  // OpenAPI スキーマ。外部 URL を指定することもできます。
  input: ['./openapi.json'],
});

それぞれのオプションについては、createOpenAPI() と createOpenAPIPage() を参照してください。

ページを生成する

loader() に staticSource() を渡します。ファイルを書き出すことなくページを生成できます。

src/lib/source.ts

import { loader } from 'fumadocs-core/source';
import { defineDocs } from 'fumadocs-mdx/macro';
import { openapi } from '@/lib/openapi'; 

const docs = defineDocs({
  dir: 'content/docs',
});

export const source = loader(
  {
    docs: docs.toFumadocsSource(),
    openapi: await openapi.staticSource({
      baseDir: 'openapi',
    }),
  },
  {
    baseUrl: '/docs',
    // 任意：ページツリーの各ページ項目にバッジを追加します
    plugins: [openapi.loaderPlugin()],
  },
);

staticSource() は、デフォルトでオペレーションごとに1ページを生成します。カスタマイズする場合は、ページの生成を参照してください。

これにより、source のページは docs と openapi の2種類になります。 LLM 向けにテキストを返す箇所など、source を使用しているすべての箇所を更新してください。

import { llms } from 'fumadocs-core/source';
import { source } from '@/lib/source';

export const docsLlms = llms(source, {
  renderPage: (page) => {
    if (page.type === 'openapi') {
      // 例: 文字列化した OpenAPI スキーマを返す
      return JSON.stringify(page.data.getSchema().bundled, null, 2);
    }

    // 以下は既存の処理...
  },
});

ドキュメントページで <OpenAPIPage /> を使用して OpenAPI ページをレンダリングします。

src/pages/docs/[...slugs].tsx

import { OpenAPIPage } from '@/components/api-page'; 

export default function Page({ slugs }: PageProps<'/docs/[...slugs]'>) {
  const page = source.getPage(slugs);
  if (!page) unstable_notFound();

  if (page.type === 'openapi') {
    return (
      <DocsPage full>
        <DocsTitle>{page.data.title}</DocsTitle>
        <DocsBody>
          <OpenAPIPage {...page.data.getOpenAPIPageProps()} />
        </DocsBody>
      </DocsPage>
    );
  }

  // ...
}

移行が完了しているか確認してください

次に進む前に、型チェックを実行してください。

npm run types:check

ページを生成する代わりに MDX ファイルをコンテンツディレクトリへ書き出す方法については、MDX ファイルを参照してください。

機能

公式の OpenAPI インテグレーションは、以下の機能をサポートしています。

API エンドポイントの基本情報
インタラクティブな API プレイグラウンド
リクエスト送信用のサンプルコード(複数のプログラミング言語に対応)
レスポンスのサンプルと TypeScript の型定義
スキーマから生成されるリクエストのパラメーターとボディ

デモ

デモを見る。

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

スタイルの生成アンカーリンクをコピー

プラグインの設定アンカーリンクをコピー

ページを生成するアンカーリンクをコピー

機能アンカーリンクをコピー

デモアンカーリンクをコピー

このページの内容

セットアップ

スタイルの生成

プラグインの設定

ページを生成する

機能

デモ