Fumadocs OpenAPI 9.0.0 版本发布：文件生成机制重构与UI升级

Fumadocs 是一个专注于文档生成的现代化工具链，其 OpenAPI 模块专门用于将 OpenAPI/Swagger 规范转换为美观实用的文档页面。本次发布的 9.0.0 版本带来了两项重要改进：文件生成逻辑的重构和用户界面的优化升级。

文件生成机制全面重构

在 9.0.0 版本中，开发团队对 generateFiles 方法进行了彻底的重构，使其行为更加一致且易于理解。这项改进主要涉及以下几个关键方面：

废弃过时的 groupByFolder 选项

groupByFolder 选项已被正式废弃，这个选项在早期版本中就已经被标记为过时。开发者现在应该使用更加强大的 groupBy 选项来实现类似功能。

增强类型安全性

新版本对类型系统进行了强化，现在 groupBy 选项只能在 per 设置为 operation 时使用。这种约束确保了API的合理使用，避免了潜在的配置错误。

全新的 name 选项设计

name 选项经历了重大变革，现在接受一个函数作为参数，提供了更大的灵活性：

generateFiles({
  input: ['./content/docs/openapi/museum.yaml'],
  output: './content/docs/openapi/(generated)',
  per: 'operation',
  name: (output, document) => {
    // 可以访问页面信息和解析后的OpenAPI模式
    return 'dir/my-file'; // 自定义输出路径
  },
});

对于需要保持向后兼容性的项目，可以通过设置 algorithm: 'v1' 来维持v8版本的行为：

generateFiles({
  name: {
    algorithm: 'v1',
  },
});

智能默认命名策略

当使用 per: 'operation' 时，系统会自动选择最合适的文件名：

1. 优先使用 operationId（如果定义）
2. 回退到端点路径或webhook名称

强大的分组功能

groupBy 选项现在支持三种分组模式：

• tag: 按照API标签分组，路径格式为 {tag}/{file}
• route: 按照端点路径分组，格式为 {endpoint}/{method}
• none: 不分组，直接使用 {file}（默认值）

用户界面显著提升

模式展示UI重新设计

新版本对OpenAPI模式的展示界面进行了全面革新，提供了更加清晰直观的数据结构呈现方式，使开发者能够更快理解API的响应和请求格式。

增强的Playground体验

改进了Playground中的请求体输入功能，现在开发者可以更方便地构建和测试API请求，特别是在处理复杂JSON结构时体验更加流畅。

递归引用问题修复

解决了在anyOf/allOf/oneOf组合模式中可能出现的递归引用显示问题，确保了复杂模式能够正确渲染。

稳定化媒体适配器API

mediaAdapters API在此版本中被标记为稳定，开发者可以放心地在生产环境中使用这一功能来处理各种媒体类型的展示需求。

升级建议

对于正在使用Fumadocs OpenAPI的项目，特别是那些依赖generateFiles功能的，建议仔细测试新版本的文件生成逻辑。虽然提供了v1算法保持兼容性，但长期来看迁移到新的name函数设计能够获得更好的灵活性和控制力。

UI方面的改进可以直接带来用户体验的提升，特别是对于需要频繁查阅API文档的开发者团队，新版界面能够显著提高工作效率。