OpenAPI
根據 OpenAPI schema 產生文件。
設定
請安裝所需的套件。
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 schema，也可以改為提供外部 URL。
input: ['./openapi.json'],
});如需了解可用選項，請參閱 createOpenAPI() 與 createOpenAPIPage()。
產生頁面
將 staticSource() 傳入您的 loader()，即可產生頁面，而不必實際寫入檔案。
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() 預設會為每個 operation 產生一個頁面。如需自訂，請參閱產生頁面。
source 的頁面現在有 docs 與 openapi 兩種類型。 請更新所有使用到 source 的地方，例如為 LLM 回傳文字的程式碼：
import { llms } from 'fumadocs-core/source';
import { source } from '@/lib/source';
export const docsLlms = llms(source, {
renderPage: (page) => {
if (page.type === 'openapi') {
// 例如：回傳序列化為字串的 OpenAPI schema
return JSON.stringify(page.data.getSchema().bundled, null, 2);
}
// 以下為您原本的流程……
},
});將 OpenAPI 頁面放在獨立的 island 中算繪，並在該 island 中以文件版面配置包裝 <OpenAPIPage />：
---
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 型別定義
- 根據 schema 產生的請求參數與 body
示範
查看示範。
How is this guide?
最後更新於
General Translation
Ferry Health
assistant-ui
Inkeep