Fumadocs OpenAPI v9

概述

此破坏性更改主要是为了解决 generateFiles() 函数的问题。

以前，它是一个简单的函数，用于从您的 OpenAPI 架构生成多个 MDX 文件/页面，与每个文档生成器相同。 我们在 Unkey、Vercel 以及 Scalar 和 Swagger 的 Museum 架构的示例等公共 OpenAPI 架构上测试了它。

由于这些架构是为不同的文档解决方案编写的，甚至是它们自定义的解决方案。 我们使 generateFiles() 过于复杂，以至于能够为各种架构样式产生最佳结果，而且自定义生成的 API 文档文件路径甚至更难。

此更新还包括：

• 架构和 playground 正文输入的更好 UI
• generateFiles() 的改进类型安全性

破坏性更改

生成文件路径的算法已更改：

• 不再生成 meta.json，请按需添加。
• per: operation：生成的路径将与您的操作 ID 相同。如果未定义，则使用您的端点路径。

按组分组

groupBy API 的行为也已更改。

自定义输出

name 选项的使用已更新，它可用于自定义文件的输出路径。

import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  name: (output, document) => {
    // page info
    console.log(output);
    // parsed OpenAPI schema
    console.log(document);
    return 'my-dir/filename';
  },
});

迁移

您可以开始使用最新的算法，或者通过以下方式保持当前行为：

import { generateFiles } from 'fumadocs-openapi';

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

请注意，即使将 algorithm 设置为 v1，也不会再创建 meta.json，您可以保留当前生成的 meta.json 文件。