OpenAPI
OpenAPI スキーマからドキュメントを生成します。
セットアップ
必要なパッケージをインストールします。
npm i fumadocs-openapi shikiスタイルの生成
次の行を追加します。
@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() を渡します。ファイルを書き出すことなくページを生成できます。
import { getCollection } from 'astro:content';
import { loader } from 'fumadocs-core/source';
import { toFumadocsSource } from '@fumadocs/astro/source';
import { openapi } from '@/lib/openapi';
export const source = loader(
{
docs: toFumadocsSource(await getCollection('docs'), await getCollection('meta')),
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);
}
// 以下は既存の処理...
},
});OpenAPI ページは専用のアイランド内でレンダリングします。このアイランドでは、<OpenAPIPage /> を Docs レイアウトでラップします。
---
import type { GetStaticPaths, InferGetStaticPropsType } from 'astro';
import Layout from '@/layouts/Layout.astro';
import { Docs } from '@/components/docs';
import { OpenAPIDocs } from '@/components/openapi-docs';
import { source } from '@/lib/source';
export const prerender = true;
export const getStaticPaths = (() => {
return source.getPages().map((page) => ({
params: { slug: decodeURI(page.slugs.join('/')) || undefined },
props: { page },
}));
}) satisfies GetStaticPaths;
type Props = InferGetStaticPropsType<typeof getStaticPaths>;
const { page } = Astro.props;
const pageTree = await source.serializePageTree(source.getPageTree());
---
{/* [!code ++:13] */}
{page.type === 'openapi' && (
<Layout title={page.data.title ?? 'My App'}>
<OpenAPIDocs
client:load
pathname={Astro.url.pathname}
params={Astro.params}
tree={pageTree}
title={page.data.title}
props={page.data.getOpenAPIPageProps()}
/>
</Layout>
)}移行が完了しているか確認してください
次に進む前に、型チェックを実行してください。
npm run types:checkページを生成する代わりに MDX ファイルをコンテンツディレクトリへ書き出す方法については、MDX ファイルを参照してください。
機能
公式の OpenAPI インテグレーションは、以下の機能をサポートしています。
- API エンドポイントの基本情報
- インタラクティブな API プレイグラウンド
- リクエスト送信用のサンプルコード(複数のプログラミング言語に対応)
- レスポンスのサンプルと TypeScript の型定義
- スキーマから生成されるリクエストのパラメーターとボディ
デモ
How is this guide?
最終更新日
General Translation
Ferry Health
assistant-ui
Inkeep