Fumadocs OpenAPI 按 Tag 分组生成 API 文档页面:从测试快照到源码实现全解析

原创2026-09-14 15:43:331,711 阅读
文章标签:前端Web框架文档UI组件开发工具SSR

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):

  1. generateFiles() / generateFilesOnly() 通过 input.getSchemas() 拿到所有 schema 的 bundled 文档;
  2. createAutoPreset(options) 把 per、groupBy、name 等选项编译成 toPages(builder) 回调(preset-auto.ts);
  3. fromSchema(id, bundled, preset) 创建 PagesBuilder,用 magic proxy 包装文档以支持惰性 $ref 解析,并调用 toPages 产出 OutputEntry<a href="https://link.gitcode.com/i/0f30b33c0ed8f4049025704c953bd955" target="_blank">]([builder.ts);
  4. 对每个非 group 条目调用 toText()(to-text.ts)生成 MDX 文本,写入内存中的 OutputFile[];
  5. 若配置了 index 与 meta,还会追加生成 <Cards> 索引页与 meta.json;
  6. 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 目录结构,从而在实际项目中精准定制生成策略。

登录后查看全文
fumadocs