Swagger(OpenAPI 3) Post路由文档编写遇YAML语法错误求助

这个错误的核心是YAML缩进层级不统一，YAML要求同一父级下的所有子项（集合项）必须从同一列开始，你的情况是第3行的summary所在层级的缩进和同级别字段没有对齐。

常见错误示例（触发报错的写法） #

openapi: 3.0.0
paths:
  /home:
   post:
      summary: 首页提交接口
      # 其余代码...

这里post的缩进比/home少了1个空格，导致后续summary的起始列和预期的集合项对齐位置不一致，触发语法错误。

修正后的正确写法 #

openapi: 3.0.0
paths:
  /home:
    post:
      summary: 首页提交接口
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string

关键注意事项 #

• 统一用2个空格缩进，绝对不要混用制表符和空格；
• 检查所有层级的字段，确保同一父节点下的子项起始列完全对齐；
• 复制外部代码时，先清除格式再调整缩进，避免隐形的缩进错乱。

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