OpenAPI

仅服务器组件

它仅在 RSC 环境中工作。

手动设置

安装所需的包。

npm i fumadocs-openapi shiki

针对 Bun PM

如果遇到任何问题，请查看 #2223。

生成样式

添加以下行：

Tailwind CSS

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

配置页面

在服务器上创建一个 OpenAPI 实例。

lib/openapi.ts

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

export const openapi = createOpenAPI({
  // OpenAPI 架构，您也可以提供外部 URL。
  input: ['./unkey.json'],
});

lib/source.ts

import { transformerOpenAPI } from 'fumadocs-openapi/server';
import { loader } from 'fumadocs-core/source';

export const source = loader({
  // 为页面树中的每个页面项添加徽章
  pageTree: {
    transformers: [transformerOpenAPI()],
  },
});

将 APIPage 添加到您的 MDX 组件中，以便在 MDX 文件中使用它。

mdx-components.tsx

import defaultComponents from 'fumadocs-ui/mdx';
import { APIPage } from 'fumadocs-openapi/ui';
import { openapi } from '@/lib/openapi';
import type { MDXComponents } from 'mdx/types';

export function getMDXComponents(components?: MDXComponents): MDXComponents {
  return {
    ...defaultComponents,
    APIPage: (props) => <APIPage {...openapi.getAPIPageProps(props)} />,
    ...components,
  };
}

APIPage 是一个 React 服务器组件。

生成文件

您可以直接从 OpenAPI 架构生成 MDX 文件。

创建一个脚本：

scripts/generate-docs.ts

import { generateFiles } from 'fumadocs-openapi';
import { openapi } from '@/lib/openapi';

void generateFiles({
  input: openapi,
  output: './content/docs',
  // 我们推荐启用它
  // 确保您的端点描述不会破坏 MDX 语法。
  includeDescription: true,
});

仅支持 OpenAPI 3.0 和 3.1。

使用脚本生成文档：

bun ./scripts/generate-docs.ts

功能

官方 OpenAPI 集成支持：

基本的 API 端点信息
交互式 API playground
发送请求的示例代码（使用不同的编程语言）
响应样本和 TypeScript 定义
从架构生成的请求参数和请求体

示例

查看示例。

手动设置

生成样式

配置页面

生成文件

功能

示例

On this page