开放API

阅读前

仅支持 OpenAPI 3.0 和 3.1。
它只在 RSC 环境下工作。

手动设置

🌐 Manual Setup

安装所需的软件包。

🌐 Install the required packages.

npm i fumadocs-openapi shiki

给 Bun PM

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

生成样式

🌐 Generate Styles

添加以下行：

🌐 Add the following line:

Tailwind CSS

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

配置插件

🌐 Configure Plugin

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

🌐 Create an OpenAPI instance on the server.

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

export const openapi = createOpenAPI({
  // the OpenAPI schema, you can also give it an external URL.
  input: ['./unkey.json'],
});

创建一个 APIPage 组件：

🌐 Create a APIPage component:

import { openapi } from '@/lib/openapi';
import { createAPIPage } from 'fumadocs-openapi/ui';
import client from './api-page.client';

export const APIPage = createAPIPage(openapi, {
  client,
});

生成页面

🌐 Generate Pages

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

🌐 You can generate MDX files directly from your OpenAPI schema.

创建一个脚本：

🌐 Create a script:

scripts/generate-docs.ts

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

void generateFiles({
  input: openapi,
  output: './content/docs',
  // we recommend to enable it
  // make sure your endpoint description doesn't break MDX syntax.
  includeDescription: true,
});

使用脚本生成文档：

🌐 Generate docs with the script:

bun ./scripts/generate-docs.ts

将 APIPage 组件添加到你的 MDX 组件中。

🌐 Add the APIPage component to your MDX Components.

mdx-components.tsx

import defaultComponents from 'fumadocs-ui/mdx';
import { APIPage } from '@/components/api-page';
import type { MDXComponents } from 'mdx/types';

// make sure you can use it in MDX files
export function getMDXComponents(components?: MDXComponents): MDXComponents {
  return {
    ...defaultComponents,
    APIPage,
    ...components,
  };
}

你也可以通过集成到 Loader API 来使用它，而无需生成真实文件。

🌐 You can also use it without generating real files by integrating into Loader API.

lib/source.ts

import { loader, multiple } from 'fumadocs-core/source';
import { openapiPlugin, openapiSource } from 'fumadocs-openapi/server';
import { docs } from 'fumadocs-mdx:collections/server';
import { openapi } from '@/lib/openapi';

export const source = loader(
  multiple({
    docs: docs.toFumadocsSource(),
    openapi: await openapiSource(openapi, {
      baseDir: 'openapi',
    }),
  }),
  {
    baseUrl: '/docs',
    plugins: [openapiPlugin()],
    // ...
  },
);

openapiSource() 是一个服务器端 API，可以直接向你的 loader() 生成页面，从而允许动态生成（例如，当模式变化时生成不同的页面树）。

它与你原始来源的类型不同，可能需要显式处理 OpenAPI 页面（例如在你的页面组件中）。

🌐 It shares a different type from your original source, explicit handling of OpenAPI pages might be necessary (e.g. in your page component).

docs/[[...slug]]/page.tsx

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

function Page() {
  const page = source.getPage('...');

  // for OpenAPI pages
  if (page.data.type === 'openapi') {
    return (
      <DocsPage full>
        <h1 className="text-[1.75em] font-semibold">{page.data.title}</h1>
        <DocsBody>
          <APIPage {...page.data.getAPIPageProps()} />
        </DocsBody>
      </DocsPage>
    );
  }

  // your original flow below...
}

或者你为大型语言模型返回文本的地方：

🌐 Or where you return text for LLM:

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

export async function getLLMText(page: InferPageType<typeof source>) {
  if (page.data.type === 'openapi') {
    // e.g. return the stringified OpenAPI schema
    return JSON.stringify(page.data.getSchema().bundled, null, 2);
  }

  // your original flow below...
}

特性

🌐 Features

官方 OpenAPI 集成支持：

🌐 The official OpenAPI integration supports:

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

演示

🌐 Demo

查看演示。

手动设置

生成样式

配置插件

生成页面

特性

演示

On this page