Swagger Editor报"bad indentation of a mapping entry"错误，OpenAPI参数定义排查

这个错误是典型的YAML缩进违规问题——毕竟OpenAPI定义基于YAML，而YAML对层级缩进的要求堪称"吹毛求疵"，你的参数定义里肯定有某个键值对（映射条目）的缩进没跟上同层级的节奏，或者嵌套层级乱了。

我给你列几个最常见的踩坑场景，对照着检查你的参数定义就行：

场景1：嵌套属性缩进过度 #

比如你可能写成了这样：

paths:
  /users/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
            schema:  # 这里错了！schema是和required同层级的参数属性，不该缩进更多
              type: integer

这里schema的缩进比同层级的required多了，导致YAML解析器错误地认为它是required的子属性，完全不符合OpenAPI的结构规范。

场景2：同层级属性缩进不足 #

另一种常见错误是参数的属性没对齐：

parameters:
  - name: page
  in: query  # 这里缩进少了！in应该和name同层级，属于同一个参数条目
    schema:
      type: integer

这个in的缩进和上面的name不一致，YAML会把它当成一个新的参数条目，自然就触发解析错误了。

场景3：混用Tab和空格 #

YAML绝对不允许同时用Tab和空格缩进，很多编辑器默认用Tab，但Swagger Editor要求统一用2个空格缩进。如果你的参数定义里混了Tab，也会触发这个错误。

正确的参数定义示例 #

对照下面的标准写法调整你的代码：

paths:
  /users/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema:  # 和required、in严格对齐，用2个空格缩进
            type: integer
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1

最后给个实用小技巧：Swagger Editor会在错误行附近标红提示，你直接盯着标红的那行，对比它上下同层级的元素（比如同是参数属性的in、required）的缩进空格数，调整成一致就搞定了。

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