配置 | Fumadocs 中文文档

文件生成器

将选项传递给 generateFiles 函数。

输入

OpenAPI 服务器对象。
input 支持的任何内容。

import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  input: ['./unkey.json'],
});

输出

输出目录。

import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  output: '/content/docs',
});

Per

自定义页面生成方式，默认值为 operation。

Operation 指的是带有特定方法的 API 端点，例如 /api/weather:GET。

mode		output
tag	具有相同标签的操作	`{tag_name}.mdx`
file	架构中的操作	`{file_name}.mdx`
operation	每个操作	`{operationId ?? endpoint_path}.mdx`)

import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  per: 'tag',
});

Group By

在 operation 模式下，可以使用文件夹对输出文件进行分组。

value	output
tag	`{tag}/{operationId ?? endpoint_path}.mdx`
route	`{endpoint_path}/{method}.mdx` (忽略 `name` 选项)
none	`{operationId ?? endpoint_path}.mdx` (默认)

import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  per: 'operation',
  groupBy: 'tag',
});

Index

生成带有链接到生成页面的卡片的索引文件。

import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  input: ['./petstore.yaml', './museum.yaml'],
  output: './content/docs',

  index: {
    // 用于生成 `href`
    url: {
      baseUrl: '/docs',
      contentDir: './content/docs',
    },
    items: [
      {
        path: 'index.mdx',
        // 可选：限制输入文件
        only: ['petstore.yaml'],
        // 可选：设置 frontmatter
        description: '所有可用页面',
      },
    ],
  },
});

Imports

向生成的 MDX 文件添加自定义导入。这对于在生成的文档中包含组件、实用工具或其他依赖项非常有用。

import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  input: ['./petstore.yaml'],
  output: './content/docs',
  imports: [
    {
      names: ['CustomComponent', 'AnotherComponent'],
      from: '@/components/custom',
    },
    {
      names: ['utils'],
      from: '@/lib/utils',
    },
    {
      names: ['API_BASE_URL'],
      from: '@/constants',
    },
  ],
});

这将向所有生成的 MDX 文件添加以下导入：

import { CustomComponent, AnotherComponent } from '@/components/custom';
import { utils } from '@/lib/utils';
import { API_BASE_URL } from '@/constants';

imports 配置对于索引文件中的卡片生成尤为重要，在那里你需要导入 source 和 getPageTreePeers 以使导航功能正常工作。

Name

一个控制 MDX 页面输出路径的函数。

import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  name: (output, document) => {
    if (output.type === 'operation') {
      const operation = document.paths![output.item.path]![output.item.method]!;
      // operation 对象
      console.log(operation);

      return 'my-dir/filename';
    }

    const hook = document.webhooks![output.item.name][output.item.method]!;
    // webhook 对象
    console.log(hook);
    return 'my-dir/filename';
  },
});

Frontmatter

自定义 MDX 文件的 frontmatter。

默认情况下，它包括：

property	description
`title`	页面标题
`description`	页面描述
`full`	始终为 true，为 Fumadocs UI 添加
`method`	操作的可用方法 (`operation` 模式)
`route`	操作的路由 (`operation` 模式)

import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  input: ['./petstore.yaml'],
  output: './content/docs',
  frontmatter: (title, description) => ({
    myProperty: 'hello',
  }),
});

Add Generated Comment

在生成的文件顶部添加一个注释，表明它们是自动生成的。

import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  input: ['./petstore.yaml'],
  output: './content/docs',
  // 添加默认注释
  addGeneratedComment: true,

  // 或提供自定义注释
  addGeneratedComment: 'Custom auto-generated comment',

  // 或禁用注释
  addGeneratedComment: false,
});

Tag Display Name

在 OpenAPI 架构中添加 x-displayName 可以控制标签的显示名称。

openapi.yaml

tags:
  - name: test
    description: this is a tag.
    x-displayName: My Test Name

OpenAPI 服务器

用于渲染页面的服务器。

Input

文件路径
外部 URL
一个函数（见下文）

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

export const openapi = createOpenAPI({
  input: ['./unkey.json'],
});

Generate Code Samples

为每个 API 端点生成自定义代码示例。确保安装类型包，以便在自定义时提供类型安全：

npm install openapi-types -D

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

export const openapi = createOpenAPI({
  generateCodeSamples(endpoint) {
    return [
      {
        lang: 'js',
        label: 'JavaScript SDK',
        source: "console.log('hello')",
      },
    ];
  },
});

此外，你也可以通过 OpenAPI 架构指定代码示例。

paths:
  /plants:
    get:
      x-codeSamples:
        - lang: js
          label: JavaScript SDK
          source: |
            const planter = require('planter');
            planter.list({ unwatered: true });

Disable Code Sample

你可以禁用特定语言的代码示例，例如禁用 cURL：

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

export const openapi = createOpenAPI({
  generateCodeSamples(endpoint) {
    return [
      {
        lang: 'curl',
        label: 'cURL',
        source: false,
      },
    ];
  },
});

Renderer

自定义页面中的组件。

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

export const openapi = createOpenAPI({
  renderer: {
    Root(props) {
      // 你自己的 (服务器) 组件
    },
  },
});

配置

On this page