generateFiles()

generateFiles() 函数用于生成 API 文档的 MDX 文件。

🌐 The generateFiles() function generates MDX files for API documentation.

请注意，页面内容仍由 APIpage 组件呈现，文档生成器仅安排每个页面要呈现的端点/Webhook。

🌐 Note that the page content is still rendered by the APIpage component, docs generator only arranges the endpoints/webhooks to render for each page.

使用

🌐 Usage

它需要一个 OpenAPI 实例。

🌐 It takes an OpenAPI instance.

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

void generateFiles({
  input: openapi,
  // The output directory.
  output: '/content/docs',
});

`per`

自定义页面内容，默认为 operation。

🌐 Customise the content of pages, default to operation.

操作是指具有特定方法（如 /api/weather:GET）的 API 端点。

模式	内容	文件路径
标签	相同标签的操作	`{tag_name}.mdx`
文件	相同模式文件中的操作	`{file_name}.mdx`
操作	每个操作	`{operationId ?? endpoint_path}.mdx`
自定义	见下文	不适用

import { generateFiles } from 'fumadocs-openapi';

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

当设置为 custom 时，你可以传入一个函数来完全自定义生成过程：

🌐 When set to custom, you can pass a function to fully customise the generation process:

Example

import { generateFiles, OperationOutput } from 'fumadocs-openapi';

void generateFiles({
  per: 'custom',
  toPages(builder) {
    const { dereferenced } = builder.document;
    const items = builder.extract();

    for (const op of items.operations) {
      const { pathItem, operation, displayName } = builder.fromExtractedOperation(op)!;

      const entry: OperationOutput = {
        type: 'operation',
        schemaId: builder.id,
        item: op,
        path: '...',
        info: {
          title: displayName,
          description: operation.description ?? pathItem.description,
        },
      };

      builder.create(entry);
    }
  },
});

当设置为 tag 时，在标签定义中添加 x-displayName 可以控制每个页面的标题。

🌐 When set to tag, adding x-displayName to the tag definition can control the title of each page.

openapi.yaml

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

`groupBy`

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

🌐 In operation mode, you can group output files with folders.

值	输出
标签	`{tag}/{operationId ?? endpoint_path}.mdx`
路由	`{endpoint_path}/{method}.mdx`（忽略 `name` 选项）
无（默认）	`{operationId ?? endpoint_path}.mdx`

import { generateFiles } from 'fumadocs-openapi';

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

`index`

生成索引文件，其中的卡片链接到已生成的页面。

🌐 Generate index files with cards linking to generated pages.

import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  index: {
    // for generating `href`
    url: {
      baseUrl: '/docs',
      contentDir: './content/docs',
    },
    items: [
      {
        path: 'index.mdx',
        // optional: restrict the input files (identical to the `input` field in server)
        only: ['petstore.yaml'],
        // optional: set frontmatter
        description: 'All available pages',
      },
    ],
  },
});

`imports`

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

🌐 Add custom imports to generated MDX files. This is useful for including components, utilities, or other dependencies in your generated documentation.

import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  imports: [
    {
      names: ['API_BASE_URL'],
      from: '@/constants',
    },
  ],
});

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

🌐 This will add the following imports to all generated MDX files:

import { API_BASE_URL } from '@/constants';

`name`

一个控制 MDX 页面输出文件名的函数。

🌐 A function that controls the output file name of MDX pages.

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 object
      console.log(operation);

      return 'my-dir/filename';
    }

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

`frontmatter`

自定义 MDX 文件的前言部分。

🌐 Customise the frontmatter of MDX files.

默认情况下，它包括：

🌐 By default, it includes:

属性	描述
`title`	页面标题
`description`	页面描述
`full`	始终为真，为Fumadocs UI添加
`_openapi`	内部属性

import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  frontmatter: (title, description) => ({
    myProperty: 'hello',
  }),
});

`addGeneratedComment`

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

🌐 Add a comment to the top of generated files indicating they are auto-generated.

import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  // Add default comment
  addGeneratedComment: true,

  // Or provide a custom comment
  addGeneratedComment: 'Custom auto-generated comment',

  // Or disable comments
  addGeneratedComment: false,
});

On this page