Fumadocs OpenAPI文档生成中的端点重复问题分析与解决方案

在Fumadocs项目中，开发者使用OpenAPI集成功能自动生成API文档时，可能会遇到一个常见问题：当多个API端点共享相同操作标签（如GET）时，文档生成过程中会出现端点丢失的情况。本文将深入分析该问题的技术背景，并提供有效的解决方案。

问题现象

当开发者按照官方示例代码配置文档生成工具时：

await OpenAPI.generateFiles({
  input: ['./api-spec.yaml'],
  output: './docs',
  per: 'operation',
  groupBy: 'tag',
})

系统会为每个API操作生成单独的MDX文件。但当遇到以下情况时：

1. GET /customers
2. GET /customers/{id}

这两个端点虽然都属于"customers"标签组，但最终可能只会生成其中一个端点的文档文件，另一个端点会被意外覆盖。

技术原理分析

该问题的根本原因在于文件命名冲突。当配置per: 'operation'时，系统默认会：

1. 使用操作类型（如GET、POST）作为基础文件名
2. 按照标签组（tag）进行目录分类

对于相同HTTP方法和相同标签组的端点：

• GET /customers → customers/get.mdx
• GET /customers/{id} → customers/get.mdx

这导致两个端点试图生成相同路径的文件，后者覆盖前者。

解决方案

临时解决方案

1. 修改生成策略：使用per: 'tag'替代per: 'operation'

await OpenAPI.generateFiles({
  // 其他配置不变
  per: 'tag'
})

这种方式会为每个标签组生成单个聚合文档，包含该组所有端点。

2. 自定义文件名：通过路径参数区分文件

await OpenAPI.generateFiles({
  // 其他配置不变
  output: (operation) => {
    const baseName = operation.path.split('/').pop();
    return `${operation.tag}/${operation.method}-${baseName}.mdx`;
  }
})

永久解决方案

Fumadocs 8.1.4及以上版本已内置修复机制，新版本会：

• 自动检测路径参数
• 为含参数的端点添加-id后缀
• 确保每个端点生成独立文件

建议开发者升级到最新版本以获得最佳体验。

最佳实践建议

1. 版本控制：始终使用最新的fumadocs-openapi包
2. 文档结构规划：提前设计合理的标签分组
3. 生成策略选择：
   • 小型API：使用per: 'tag'聚合展示
   • 大型API：使用per: 'operation'分拆文档
4. 自定义输出：利用output回调实现灵活的文件命名

通过理解这些技术细节和解决方案，开发者可以更高效地利用Fumadocs生成完整、准确的API文档。