如何修复SwaggerHub编辑器中的"重复映射键"错误？

你的问题核心是YAML缩进完全不符合规范，SwaggerHub的解析器因缩进混乱误报了“重复映射键”错误，调整缩进即可解决所有问题。

错误根源 #

YAML是严格依赖缩进的层级语言，你的代码存在以下缩进问题：

• /widgets/home-page 和 get 缩进层级相同，解析器会把它们当成paths下的同级重复键（实际get应该是路径的子属性）
• tags、description等操作属性未缩进在get下方，被误判为paths的同级属性，进一步触发解析异常

修正后的完整代码 #

paths:
  /widgets/home-page:
    get:
      tags:
        - home Page APIs sfssf
      description: asd
      operationId: getwidgets
      responses:
        '200':
          description: home page catregories widgets
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  # 注意：format字段用于指定基础数据格式（如email、uuid），若要引用外部Schema需用$ref
                  # $ref: 'https://api.inspireuplift.com/api/v1/widgets/home-page'
                  format: https://api.inspireuplift.com/api/v1/widgets/home-page

OpenAPI YAML核心缩进规则 #

• paths下的每个接口路径，缩进2个空格
• 路径下的HTTP方法（get/post等），在路径基础上再缩进2个空格
• HTTP方法下的tags、responses等操作属性，继续缩进2个空格
• 所有同级属性必须保持统一缩进（建议用2个空格，禁止混用制表符）

额外规范提示 #

你代码里的format字段用法不符合OpenAPI标准：format是用来定义基础数据类型的格式（如type: string搭配format: email），如果需要引用外部API的Schema结构，应该使用$ref字段，示例已在代码中注释说明。

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