Fumadocs OpenAPI v9

概览

🌐 Overview

这个重大更改主要是为了解决 generateFiles() 函数的问题。

🌐 This breaking change is mainly made to address problems of generateFiles() function.

以前，它是一个简单的功能，用于从你的 OpenAPI 模式生成多个 MDX 文件/页面，就像其他文档生成器一样。 我们在公共 OpenAPI 模式上进行了测试，例如 Unkey、Vercel，以及来自 Scalar 和 Swagger Museum 模式的示例。

🌐 Previously, it was a simple function to generate multiple MDX files/pages from your OpenAPI schema, same as every docs generator. We tested it on public OpenAPI schemas such as Unkey, Vercel and examples from Scalar and Swagger's Museum schema.

由于这些模式是为不同的文档解决方案，甚至是它们的自定义方案编写的。我们使 generateFiles() 过于复杂，无法为各种模式风格生成最佳结果，而且定制 API 文档生成的文件路径更加困难。

🌐 Since these schemas were written for different docs solutions, or even their custom ones. We made generateFiles() too complicated to be capable of producing best results for various schema styles, and it's even harder to customise the generated file paths of API docs.

此更新还包括：

🌐 This update also include:

• 为架构和演示区主体输入提供更好的用户界面
• generateFiles() 的类型安全性得到改进

重大更改

🌐 Breaking Changes

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

🌐 The algorithm for generating file paths is changed:

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

分组

🌐 Group By

groupBy API 的行为也发生了变化。

🌐 The behaviour of groupBy API is also changed.

自定义输出

🌐 Customise Output

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

🌐 The usage of name option is renewed, it can be used to customise the output path of files.

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';
  },
});

迁移

🌐 Migration

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

🌐 You can start using the latest algorithm, or keep the current behaviour with:

import { generateFiles } from 'fumadocs-openapi';

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

请注意，即使将 algorithm 设置为 v1，它也不会再创建 meta.json，你可以继续使用当前生成的 meta.json 文件。

🌐 Note that it won't create meta.json anymore even with algorithm set to v1, you can keep your current generated meta.json files.