Express.js中Swagger配置报YAMLSyntaxError的排查求助

在Express.js项目中使用swagger-jsdoc和swagger-ui-express生成接口文档，通过/docs路由访问时，路由末尾的Swagger注释代码如下：

/**
 * @swagger
 * /table/join:
 *    post:
 *      summary: Join table
 *      requestBody:
 *        description: Table and user uuids
 *        required: true
 *        content:
 *          application/json:
 *            schema:
 *              type: object
 *              properties:
 *                user_id:
 *                  type: string
 *                table_uuid:
 *                  type: string
 *      tags:
 *        - Table
 *      responses:
 *        "200":
 *          description: Your table created successfully.
 *          content:
 *              application/json:
 *                  schema:
 *                      type: object
 *                      properties:
 *                          resultMessage:
 *                              $ref: '#/components/schemas/ResultMessage'
 *                          resultCode:
 *                              $ref: '#/components/schemas/ResultCode'
 *                          uuid:
 *                              type: string
 *       "400":
 *          description: Please provide all the required fields!
 *          content:
 *              application/json:
 *                  schema:
 *                      $ref: '#/components/schemas/Result'
 *       "500":
 *          description: An internal server error occurred, please try again.
 *          content:
 *              application/json:
 *                  schema:
 *                      $ref: '#/components/schemas/Result'
 */

无论如何调整缩进，都会出现以下错误：

Error in src/api/controllers/user-table/join-table.js :
YAMLSyntaxError: All collection items must start at the same column at line 3, column 6:

     summary: Join table
     ^^^^^^^^^^^^^^^^^^^…

解决方法 #

• 修复缩进一致性：YAML对缩进要求严格，所有同级响应项必须对齐到同一列。观察代码可知"400"和"500"的缩进比"200"少一个空格，调整后三者缩进需保持一致。
• 替换转义引号：代码中的"是HTML转义双引号，在JS注释中直接使用普通双引号"即可，转义字符会导致YAML解析失败。
• 验证Swagger定义完整性：确保swagger-jsdoc配置的components.schemas部分已正确定义ResultMessage、ResultCode和Result这几个Schema，否则会导致引用失败。示例配置如下：

const swaggerJsdoc = require('swagger-jsdoc');
const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'API Documentation',
      version: '1.0.0',
    },
    components: {
      schemas: {
        ResultMessage: {
          type: 'string',
          description: '返回的提示信息'
        },
        ResultCode: {
          type: 'integer',
          description: '返回状态码'
        },
        Result: {
          type: 'object',
          properties: {
            resultMessage: { $ref: '#/components/schemas/ResultMessage' },
            resultCode: { $ref: '#/components/schemas/ResultCode' }
          }
        }
      }
    }
  },
  apis: ['./src/api/controllers/**/*.js'], // 确保路径覆盖所有含Swagger注释的文件
};
const swaggerSpec = swaggerJsdoc(options);

• 重启服务验证：修改完成后重启Express服务，访问/docs路由检查接口文档是否正常加载。

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