Next.js集成Swagger UI遇Error: Cannot convert undefined or null to object

我正在给带API的Next.js项目集成Swagger UI，但模块返回错误：Error: Cannot convert undefined or null to object。已经严格按照next-swagger-doc的文档步骤操作，单独使用swagger-jsdoc也出现相同错误，推测问题出在swagger-jsdoc模块上。

以下是我的Swagger注释代码，供排查参考：

/**
* @swagger
* /api/user/users:
*   get:
*     summary: 获取指定学期/学年的用户列表，或默认获取当前活跃学期的用户
*     description: 如果指定学期和学年，返回对应学期的所有用户；未指定则返回当前活跃学期的用户。
*     parameters:
*       - in: query
*         name: semester
*         schema:
*           type: string
*         required: false
*         description: 要获取用户的学期（1或2）。
*       - in: query
*         name: year
*         schema:
*           type: string
*         required: false
*         description: 要获取用户的学年（例如：'2023'）。
*     responses:
*       200:
*         description: 用户列表
*         content:
*           application/json:
*             schema:
*               type: array
*               items:
*                 type: object
*                 properties:
*                   id:
*                     type: string
*                   // Add other user properties here
*       400:
*         description: 学期或学年参数无效
*       404:
*         description: 未找到当前活跃学期
*       405:
*         description: 请求方法不允许
*       500:
*         description: 获取用户列表失败
*/

排查与解决方案 #

• 移除非法注释：Swagger的YAML语法不支持JavaScript风格的//单行注释，代码中的// Add other user properties here会导致swagger-jsdoc解析YAML时出错，进而触发转换错误。建议直接删除该占位符，或改用YAML的#注释格式。
• 检查YAML语法完整性：确保所有Swagger注释的缩进、结构完全符合YAML规范，比如每个层级的缩进一致，属性后都有冒号，没有未闭合的结构。
• 补全Schema定义：200响应中的用户对象properties部分存在未完成的占位符，建议补全所有必要的用户属性定义，避免解析时出现空值/未定义的结构。

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