实现Express REST API的Swagger文档时出现YAMLSemanticError如何解决？

错误根因 #

报错是你写的Swagger注释不符合OpenAPI的YAML语法规范，存在两处问题：

• 路径参数写法错误：Express路由用:参数名定义路径参数，但Swagger要求路径参数必须用{参数名}格式包裹
• YAML语法错误：路径作为YAML的映射键，末尾必须加冒号，你写的路径行末尾没有冒号，导致YAML解析触发语义错误

你的Express路由本身写法是正确的，仅Swagger注释的语法和Express路由语法存在差异，所以只有生成接口文档时会触发报错，不影响路由本身的运行。

修复方法 #

替换你对应带email参数接口的Swagger注释为以下内容即可：

/** 
 * @swagger 
 * /api/v1/listallstaff/{email}:
 *   get: 
 *     description: Get single employee by email
 *     parameters:
 *       - name: email
 *         in: path
 *         required: true
 *         description: Employee email address
 *         schema:
 *           type: string
 *     responses:  
 *       200: 
 *         description: Return matched employee information
 *   
 */

修改完成后重启服务，报错就会消失，Swagger文档也会正确识别该接口的路径参数，支持直接在线调试。

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