OpenAPI paths连续用多个$ref报重复映射键错误，如何实现接口拆分？

你遇到的报错是因为YAML语法不允许同一映射下存在重复键，你在paths下连续定义多个$ref属于重复键，OpenAPI原生的$ref不支持直接在paths字段下批量引用多个路径集合文件，可通过以下方案解决：

方案1：保留现有子文件结构，用预编译工具合并（生产环境最常用） #

不需要改动你现有子文件的内容，只要引入OpenAPI专用打包工具自动合并多个路径文件即可：

操作步骤： #

1. 现有的employee/resource.api.yaml、projects/resource.api.yaml、customers/resource.api.yaml三个子文件保持现有路径集合的写法不变。
2. 选择对应的工具执行合并操作即可得到完整的OpenAPI文件：
   • Node.js生态可以用swagger-cli，执行命令swagger-cli bundle 主文件.yaml -o 合并后完整文件.yaml -t yaml
   • 对校验规则要求高的场景可以用redocly-cli，配置简单规则后执行redocly bundle 主文件.yaml -o 合并后完整文件.yaml
   • Java SpringBoot生态用SpringDoc的话，直接配置springdoc.paths-to-match扫描多个路径yaml文件即可自动合并，不需要额外打包步骤。

方案2：原生OpenAPI语法实现（无需额外工具） #

如果你不想引入额外编译工具，可以调整拆分粒度，用OpenAPI原生的路径引用规则实现：

操作步骤： #

1. 把每个接口路径单独拆分为独立的yaml文件，比如/employee/{id}的定义存放在./employee/paths/getEmployeeById.yaml中。
2. 主文件的paths字段下逐个路径引用即可：

openapi: 3.0.3
info:
  title: example  
servers:
  - url: https://example.net/api
security:
  - apiKey: []
paths:
  /employee/{id}:
    $ref: './employee/paths/getEmployeeById.yaml'
  /employee/{id}/addresses:
    $ref: './employee/paths/getEmployeeAddresses.yaml'
  /projects/{id}:
    $ref: './projects/paths/getProjectById.yaml'
  # 其余接口路径以此类推逐个引用

这个方案完全符合OpenAPI官方语法规范，兼容性最好，缺点是接口数量多的时候主文件需要罗列所有路径，维护成本稍高。

方案3：YAML合并键写法（兼容性一般） #

如果你的OpenAPI解析器支持YAML 1.2的合并键（<<）语法，可以直接用以下写法：

paths:
  <<: 
    $ref: './employee/resource.api.yaml'
  <<: 
    $ref: './projects/resource.api.yaml'
  <<: 
    $ref: './customers/resource.api.yaml'

注意：该写法依赖解析器对YAML合并键的支持，部分OpenAPI工具不识别该语法，兼容性较差，不推荐生产环境使用。

内容的提问来源于stack exchange，提问作者user527614