Fumadocs OpenAPI 按 Tag 分组生成 API 文档页面:从测试快照到源码实现全解析
Fumadocs OpenAPI 按 Tag 分组生成 API 文档页面:从测试快照到源码实现全解析
Fumadocs 的 OpenAPI 集成支持把一份 OpenAPI 规范文档自动生成一套结构化的 MDX 页面,用于在文档站中渲染交互式 API 参考。本文以仓库中 packages/openapi/test/out/products-group-by-tag.md 这份测试快照为切入点,完整解析「按 Tag 分组、每个操作一个页面(per: 'operation' + groupBy: 'tag')」的生成结果,并深入源码讲解分组算法、命名算法(v1/v2)、路由路径转换、meta.json 生成与 Tag 层级支持,帮助你在实际项目中精确控制 API 文档的目录结构。
快照文件的本质:它是什么
packages/openapi/test/out/products-group-by-tag.md 并不是手写的示例文档,而是 Vitest 快照测试的产物。在 packages/openapi/test/index.test.ts 中,测试用例 Generate Files - groupBy tag per operation 调用 generateFilesOnly(),对测试夹具 packages/openapi/test/fixtures/products.yaml 执行页面生成,随后通过 toMatchFileSnapshot() 把全部输出文件序列化后与这份快照做对比。
test('Generate Files - groupBy tag per operation', async () => {
const out = await generateFilesOnly({
input: createOpenAPI({
input: {
products: path.join(cwd, './fixtures/products.yaml'),
},
}),
per: 'operation',
groupBy: 'tag',
name: {
algorithm: 'v1',
},
});
await expect(stringifyOutput(out)).toMatchFileSnapshot('./out/products-group-by-tag.md');
});
也就是说,这份快照真实反映了「每个操作生成一个页面,并按 OpenAPI Tag 分组放进对应文件夹」的完整输出形态,是理解生成器行为的"黄金样例"。快照中的 stringifyOutput 会按输出路径排序,并把每个文件的内容包裹成带 title 的代码块,例如 inventory/inventory/productid/get.mdx 这样的标题就是实际生成的文件路径。
输入:最小的双 Tag 测试夹具
生成该快照所用的输入是 packages/openapi/test/fixtures/products.yaml,一份 OpenAPI 3.0.3 的极小规范,包含两个 Tag 与两条路径:
- Tag:
Products("Operations related to products.")、Inventory("Operations related to inventory."); /products/{productId}的 GET 操作,operationId: getProductDetails,只挂Products一个 Tag;/inventory/{productId}的 GET 操作,operationId: getInventoryForProduct,同时挂Inventory和Products两个 Tag。
第二个操作同时挂两个 Tag,是理解按 Tag 分组行为的关键:同一个操作会分别在两个 Tag 文件夹下各生成一份页面。快照中因此出现了三份 MDX 文件:
| 生成路径 | 对应操作 | 所在 Tag 组 |
|---|---|---|
inventory/inventory/productid/get.mdx |
GET /inventory/{productId} |
Inventory |
products/inventory/productid/get.mdx |
GET /inventory/{productId} |
Products |
products/products/productid/get.mdx |
GET /products/{productId} |
Products |
每一份文件内容几乎相同(只是路径参数不同),这就是分组模式"复制而非移动"的直观体现。
输出文件结构逐段拆解
以 inventory/inventory/productid/get.mdx 为例,生成的文件由四部分组成:frontmatter、自动生成注释、可选的 import、以及 MDX 布局组件。
Frontmatter 与 _openapi 元数据
---
title: Get product inventory
description: Retrieve inventory details for a specific product.
full: true
_openapi:
preload:
- products
method: GET
webhook: false
toc: []
structuredData:
headings: []
contents:
- content: Retrieve inventory details for a specific product.
---
title/description取自操作的summary/description(见 packages/openapi/test/fixtures/products.yaml);full: true由生成器默认强制写入(在 to-text.ts 的toText()中固定添加),表示该页面是全宽渲染的 API 页面;_openapi.preload指向输入 schema 的 ID(这里是products),运行时用于预取对应文档数据;_openapi.method、_openapi.webhook只在单操作/单 Webhook 页面出现(对应 builder.ts 中getPageProps的输出形态);structuredData与toc是运行时静态数据缓存,由 to-static-data.ts 生成,用于加速渲染。
这段 frontmatter 的序列化逻辑在 to-text.ts 的 generateDocument() 中完成:先用 yaml 的 stringify 把 frontmatter 对象序列化并包在 --- 中,再拼接后续内容。
自动生成注释与 Layout 组件
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
该注释默认开启,可通过 addGeneratedComment 选项关闭或替换为自定义文本(false 关闭、字符串自定义)。随后是页面主体——一个默认导出的布局函数:
export default function Layout(props) {
const { APIPage, OpenAPIPage } = props.components ?? {};
// "APIPage" is the old name from v10, this allows both for backward compatibility
const Comp = OpenAPIPage ?? APIPage;
return (
<>
{props.children}
<Comp document="products" operations={[{"path":"/inventory/{productId}","method":"get"}]} />
</>
);
}
这个模板的生成逻辑在 to-text.ts 的 pageContent() 中:document 传入 schema ID,operations 以 [{path, method}] 数组的形式把当前页面要渲染的操作传给组件。OpenAPIPage ?? APIPage 的兼容写法保证 v10 旧组件名(APIPage)仍然可用。也就是说,生成的每个 .mdx 文件本身没有内联接口详情,而是把操作索引交给文档站侧的 OpenAPIPage 组件去动态渲染,页面与运行时渲染彻底解耦。
groupBy: 'tag' 的分组实现
分组逻辑集中在 packages/openapi/src/utils/pages/preset-auto.ts 的 group() 函数中。当 groupBy === 'tag' 时,会先扫描 document.tags 建立 name -> TagObject 的映射,然后对每个操作读取其 tags 数组:
- 只采纳用于导航的 Tag:对于 OpenAPI 3.2,Tag 上的
kind字段若存在且不是nav则跳过(见 preset-auto.ts); - 没有任何导航 Tag 的操作会被归入名为
unknown的分组,并且只在第一次出现时打印一条警告[Fumadocs OpenAPI] found operations without tags, they will be grouped under "unknown".(对应测试Generate Files - groupBy tag with tag hierarchy中对console.warn的断言); - 每个 Tag 对应一个
OutputGroup,组内条目通过path.join(group.path, fileName)拼接出最终路径。
其他可选的 groupBy 取值包括:
route:按路由路径分组,路径为{routePath}/{method}.mdx,会忽略name选项;none(默认):所有文件平铺在输出根目录;- 函数:接收每个输出条目,返回分组显示名,再经
slugify转成文件夹名。
命名算法 v1 与 v2 的区别
快照的生成配置中 name: { algorithm: 'v1' } 直接决定了文件名。在 preset-auto.ts 的 nameFn 中:
- v2(默认):如果操作定义了
operationId,直接用operationId作为文件名(如getInventoryForProduct.mdx,见 products-with-meta+groupby.md); - v1:忽略
operationId,始终使用routePathToFilePath(path)/method.toLowerCase(),即"路径段 + 方法名",这就是快照中出现inventory/productid/get这种深层路径的原因。
slugify 默认实现为 s.replace(/\s+/g, '-').toLowerCase(),你可以传入自定义函数控制 Tag 名到文件夹名的转换。两种算法由 algorithm: 'v2' | 'v1' 选择,对应 Fumadocs OpenAPI v9/v8 的路径生成行为,兼顾了从旧版本升级后的路径稳定性。
路由路径到文件路径的转换
无论文件名用哪种算法,Tag 文件夹下的深层结构都来自 routePathToFilePath。该函数定义在 builder.ts:
routePathToFilePath(path) {
return path
.toLowerCase()
.replaceAll('.', '-')
.split('/')
.flatMap((v) => {
if (v.startsWith('{') && v.endsWith('}')) return v.slice(1, -1);
if (v.length === 0) return [];
return v;
})
.join('/');
}
规则为:整体小写;. 替换为 -;按 / 分段;{productId} 这类路径参数去掉花括号只保留参数名;空段丢弃。因此 /inventory/{productId} 变成 inventory/productid,/products/{productId} 变成 products/productid,最终拼上 get 即得 inventory/productid/get。
从生成器到文件的完整调用链
把上面的逻辑串起来,一次页面生成的完整链路是(入口见 generate-file.ts):
generateFiles()/generateFilesOnly()通过input.getSchemas()拿到所有 schema 的 bundled 文档;createAutoPreset(options)把per、groupBy、name等选项编译成toPages(builder)回调(preset-auto.ts);fromSchema(id, bundled, preset)创建 PagesBuilder,用 magic proxy 包装文档以支持惰性$ref解析,并调用toPages产出OutputEntry<a href="https://link.gitcode.com/i/0f30b33c0ed8f4049025704c953bd955" target="_blank">]([builder.ts);- 对每个非 group 条目调用
toText()(to-text.ts)生成 MDX 文本,写入内存中的OutputFile[]; - 若配置了
index与meta,还会追加生成<Cards>索引页与meta.json; beforeWrite钩子可以对最终文件列表做增删改(比如按自己的规范重命名),随后统一写入output目录。
其中 extract() 会同时收集 paths 下的普通操作与 webhooks 下的 Webhook(builder.ts),因此 Webhook 也能参与相同的分组与命名流程。
Tag 层级与 meta.json:导航结构的完整拼图
按 Tag 分组并不只生成页面,还负责搭建导航元数据。OpenAPI 3.2 的 Tag 支持 parent 与 kind 字段,tag-hierarchy.yaml 就演示了 store -> products / inventory 的父子层级(其中 beta 是 kind: badge,不会被当作导航分组)。在 group() 中(preset-auto.ts),带 parent 的 Tag 会递归创建父级 OutputGroup,并用 seen 集合防御非法的循环引用;父组路径由 path.join(parent.path, slugify(name)) 拼接,从而形成嵌套目录。
当开启 meta: true 时,generateMeta()(generate-file.ts)会为每个 group 生成一份 meta.json。结合 products-with-meta+groupby.md 可以看到效果:
{
"title": "Inventory",
"description": "Operations related to inventory.",
"pages": [
"getInventoryForProduct"
]
}
根目录还会生成一份汇总的 meta.json(pages: <a href="https://link.gitcode.com/i/7fe3592b81f35417926d5cad1036bf6a" target="_blank">"products", "inventory"])。folderStyle 选项可切换为 separator,把分组折叠成 Fumadocs 导航中的分隔符样式。由于 /inventory/{productId} 同时挂两个 Tag,它会在 products 与 inventory 两个组的 meta.json 中各自出现一次。需要说明的是,meta: true 只是兜底的便利开关,[generate-file.ts 的注释明确建议:为了灵活性,更推荐你在实际项目中手写 meta.json,而只让生成器产出页面本身。
实操建议与注意事项
- 目录结构取决于「标签 × 算法」组合:同一操作挂多个 Tag 会产生多份副本页面,多 Tag 会显著放大文件数量,写规范时应有意识控制操作的
tags数量; - 默认用 v2 + operationId:只要规范里 operationId 命名规范,默认配置就能得到扁平、可读的路径;需要保持旧版 Fumadocs OpenAPI v8 的路径(
{tag}/{route}/{method})时才显式指定algorithm: 'v1'; - 不要手改生成文件:所有生成文件都带"Do not edit"注释,任何改动都应通过修改 OpenAPI 规范或生成配置后重新运行命令完成;
watch: true可监听 schema 文件变化自动重新生成(generate-file.ts 中实际封装了 chokidar,建议复杂场景自行配置); - 验证手段现成:修改分组逻辑后,可仿照 index.test.ts 用 Vitest 快照测试锁定输出形态,避免导航结构在迭代中悄悄变化;
- 无 Tag 的操作会落入
unknown分组并触发警告,规范审核时应把"所有操作都有导航 Tag"作为检查项之一。
至此,你已能从一份测试快照出发,逆向理解 Fumadocs OpenAPI 页面生成的完整机制——输入规范、分组模式、命名算法、路径转换与导航元数据如何共同决定最终文档站的 API 目录结构,从而在实际项目中精准定制生成策略。