Swagger用$ref引入多路径文件报错Map key must be unique如何解决

问题原因 #

标准OpenAPI/Swagger依赖的JSON Schema规范中，$ref仅支持传入单个字符串路径，不支持数组格式；同时YAML语法不允许同一个映射下出现重复的键，这就是你两次配置失效的核心原因。

解决方案 #

方案1：按路径前缀分别引用（原生规范支持，无额外依赖） #

如果不同模块的路径有明确的前缀区分，比如注册模块路径均为/register/*，管理员模块路径均为/admins/*，可直接在paths下对应前缀位置分别引用：

...
tags:
  $ref: "tags.yaml"
paths:
  /register:
    $ref: "../register/paths.yaml"
  /admins:
    $ref: "../admins/paths.yaml"

方案2：YAML多值合并语法（适合路径无重复的场景） #

如果两个外部paths.yaml中存储的都是完整的路径键值对，且路径名完全没有重复，可以用YAML合并键<<引入多个外部文件，自动合并到当前paths节点：

...
tags:
  $ref: "tags.yaml"
paths:
  <<: 
    - $ref: "../register/paths.yaml"
    - $ref: "../admins/paths.yaml"

注意：部分旧版本Swagger解析工具可能不支持多值合并语法，若不生效可使用第三种方案。

方案3：构建工具预合并（兼容性最强，适合复杂项目） #

对于复杂的多模块Swagger配置，可以通过工具提前将分散的配置文件打包为单文件，避免解析兼容性问题。以swagger-cli为例：

• 安装工具：npm install -g swagger-cli
• 执行打包命令：swagger-cli bundle 你的主配置文件.yaml --outfile 打包后配置文件.yaml --type yaml
  工具会自动识别所有$ref引用的外部文件，合并成符合规范的单份Swagger配置。

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