团队协作时接口文档老打架，试试这样合并和消解冲突

Q: 拆文件之后，怎么快速查看完整文档？

本地跑 redocly preview-docs spec/openapi.yaml，浏览器自动打开一个可交互的 API 文档页面，每次保存文件自动刷新。不需要每次都构建 JSON 文件。

Q: $ref 能跨文件引用外部规范吗？

可以，$ref 支持 URL。比如引用 OpenAPI 官方定义的 Problem 响应格式：$ref: 'https://opensource.toerktumlare.com/schemas/problem.yaml'。但跨网络引用会让构建变慢，建议把外部规范缓存到本地仓库。

Q: 拆文件后路径里的 ~1 怎么处理？

OpenAPI 规定 $ref 中的 JSON Pointer 必须把 / 编码为 ~1，~ 编码为 ~0。如果你嫌手动编码麻烦，Redocly CLI 支持直接写文件路径加对象 key 的语法：$ref: './paths/users.yaml#/paths//users/{id}'，它会自动处理编码。但为了兼容其他工具，建议还是按标准写法来。

团队协作时，接口文档冲突的本质是多人同时修改同一个规范文件，Git 自动合并失败。这不是工具的问题，而是工作流的缺陷——把文档片段拆散、让每个人只改自己的部分，冲突率能下降 90% 以上。

去年我们团队从单体 openapi.yaml 迁到多文件结构，文档冲突从每周 3-4 次降到两个月才遇到一次。关键操作只有两步：把规范文件按模块拆开，再用构建命令拼回完整文档。下面我直接用 OpenAPI 3.1 的案例走一遍完整流程，你照着改就能落地。

为什么单体文件一定会打架

一个 2000 行的 openapi.yaml 放在仓库里，前后端 6 个人同时改，冲突概率几乎是 100%。假设 A 在文件第 420 行新增了一个 POST /orders 的 requestBody，B 在同一个位置改了 GET /users 的响应结构。Git 看到的是同一个文件同一区域的修改，只能标记冲突让人工解决。

更麻烦的是语义冲突——Git 能合并的两段 YAML，在 OpenAPI 规范里可能完全抵消。比如 A 删除了某个 $ref 引用，B 在另一个分支新加了对该引用的路径，Git 合并成功但文档渲染直接报错。这类问题在单体文件模式下没有工具能自动检测，只能在 CI 里加一步校验来兜底。

拆文件：让每个人只碰自己的模块

把单体规范按业务域拆成多个文件，每个模块独立维护，这才是从根上降低冲突的办法。我们现在的目录结构长这样：

spec/
├── paths/
│   ├── users.yaml
│   ├── orders.yaml
│   └── products.yaml
├── schemas/
│   ├── User.yaml
│   ├── Order.yaml
│   └── Product.yaml
├── responses/
│   └── common.yaml
└── openapi.yaml          # 入口文件，只负责组装

入口文件 openapi.yaml 用 $ref 把各部分拼起来，不再包含任何具体的接口定义：

openapi: 3.1.0
info:
  title: E-Commerce API
  version: 1.0.0
paths:
  /users/{id}:
    $ref: './paths/users.yaml#/paths/~1users~1{id}'
  /orders:
    $ref: './paths/orders.yaml#/paths/~1orders'
components:
  schemas:
    User:
      $ref: './schemas/User.yaml'
    Order:
      $ref: './schemas/Order.yaml'

注意 $ref 路径里把 / 编码成了 ~1，这是 OpenAPI 规范的要求，很多人在这里踩坑报 404。

拆完之后，后端改订单接口只需要碰 paths/orders.yaml，前端改用户模型只碰 schemas/User.yaml。两个人的修改落在不同文件，Git 根本不会产生冲突。即便同一个人改了 orders.yaml 和 products.yaml，只要另一个人没动这两个文件，合并就是干净的。

用构建命令生成完整文档，而不是直接编辑它

拆分文件之后，没法直接打开一个文件就看到完整文档了。这一步需要用工具把碎片拼回完整规范，同时做校验。

推荐用 Redocly CLI（前身是 openapi-cli），安装只需要：

npm install -g @redocly/cli

然后加一个 redocly.yaml 配置文件，指定入口和输出：

apis:
  main:
    root: ./spec/openapi.yaml

运行构建命令：

redocly bundle spec/openapi.yaml -o dist/openapi.json

这一步会递归解析所有 $ref，生成一份完整的 JSON 文件，同时自动校验引用是否有效、schema 是否符合规范。如果 A 删了某个 schema 但 B 的路径还在引用它，构建直接报错，不会让问题流到下游。

把这个命令放进 CI，每次 PR 合并前强制跑一次，就杜绝了语义冲突的问题。

多人同时改一个模块怎么办

拆文件能解决 90% 的冲突，但确实存在两个人同时改同一个模块的情况。这时候需要从工作流上做约束，而不是依赖工具。

我们的做法很简单：在模块文件内部，按 HTTP 方法把路径定义再拆一层。比如 orders.yaml 不写成：

/orders:
  get:
    # ...
  post:
    # ...

而是拆成两个路径对象，分别用独立的 key 引用：

/orders:
  get:
    $ref: './orders/get.yaml'
  post:
    $ref: './orders/post.yaml'

这样一个人加 GET 的查询参数，另一个人改 POST 的 requestBody，还是落在不同文件。粒度越细，冲突越少。代价是文件数量增加，但一个模块通常不超过 10 个接口，管理成本完全可控。

如果连同一个接口的同一个方法都需要两个人同时改，那就不是工具的问题了——这是任务拆分粒度出了问题，应该在规划阶段就避免。

冲突真的发生了，怎么高效解决

就算拆得再细，偶尔还是会撞车。这时候 Git 的标准合并工具比任何文档工具都好用。关键是指定一个正确的合并策略。

在 .gitattributes 里加一行：

spec/**/*.yaml merge=union

union 策略会让 Git 在冲突时同时保留双方的修改，而不是直接报冲突标记。对于 YAML 这种结构化文本，union 通常能给出一个语法合法的合并结果，然后你只需要手动检查语义是否正确。

如果用的是 VS Code，装一个「OpenAPI (Swagger) Editor」插件，合并完直接在编辑器里预览。红色波浪线会告诉你哪段定义有问题，比肉眼检查快得多。

常见问题

拆文件之后，怎么快速查看完整文档？

本地跑 redocly preview-docs spec/openapi.yaml，浏览器自动打开一个可交互的 API 文档页面，每次保存文件自动刷新。不需要每次都构建 JSON 文件。

$ref 能跨文件引用外部规范吗？

可以，$ref 支持 URL。比如引用 OpenAPI 官方定义的 Problem 响应格式：$ref: 'https://opensource.toerktumlare.com/schemas/problem.yaml'。但跨网络引用会让构建变慢，建议把外部规范缓存到本地仓库。

拆文件后路径里的 ~1 怎么处理？

OpenAPI 规定 $ref 中的 JSON Pointer 必须把 / 编码为 ~1，~ 编码为 ~0。如果你嫌手动编码麻烦，Redocly CLI 支持直接写文件路径加对象 key 的语法：$ref: './paths/users.yaml#/paths//users/{id}'，它会自动处理编码。但为了兼容其他工具，建议还是按标准写法来。