Swagger 2.0解析报错：重复映射键，添加公共参数id失败

问题根源 #

你在第52行添加公共参数id时，同一个层级下重复定义了相同的键名——要么是parameters数组里重复声明了id参数，要么是某个对象结构里重复使用了同一个key。Swagger的YAML/JSON格式要求同一层级的键必须唯一，重复就会触发这个解析报错。

排查修复步骤 #

• 直接定位到第52行，检查周围代码：
  1. 确认是否已经在其他位置（比如接口独立参数列表、全局公共参数块）定义过同名的id参数，导致重复声明；
  2. 核对YAML缩进格式——有时候缩进错误会让Swagger解析器误判层级，把不同层级的key识别为同一层级，引发重复错误。
• 修复方案：
  • 如果确实重复定义了id参数，删除其中一个重复条目即可；
  • 如果需要全局复用公共参数，不要重复编写参数内容，使用$ref引用全局定义的参数：

    # 先在全局parameters节点定义公共id参数
    parameters:
      IdParam:
        name: id
        in: query
        type: integer
        required: true
    
    # 接口中直接引用该公共参数
    paths:
      /api/xxx:
        get:
          parameters:
            - $ref: '#/parameters/IdParam'
    

• 修改完成后，可通过Swagger Editor工具校验文档，确认格式合规。

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