Swagger UI配置报错：TypeError: Cannot read properties of undefined (reading 'schemas')

核心修复点 #

你的代码存在两个关键问题引发了该错误：

• $ref值未加引号：YAML语法中，包含#的字符串必须用引号包裹，否则会被解析为无效语法。需将$ref: #/components/schemas/Accounttypes修改为$ref: '#/components/schemas/Accounttypes'。
• 确保注释块被完整扫描：检查swagger-jsdoc的配置，确认当前文件路径已被包含，保证components和paths的注释块都能被正确读取。

修正后的代码 #

/**
 * @swagger
 * components:
 *      schemas:
 *          Accounttypes:
 *              type: string
 */

/**
 * @swagger
 * paths:
 *  /api/accounttypes/:
 *      get:
 *          summary : Some summary
 *          tags:
 *              - Account Types
 *          description: Some description
 *          responses:
 *              '200':
 *                  description: Success Description
 *                  content:
 *                      application/json:
 *                          schema:
 *                              type: array
 *                              items:
 *                                  $ref: '#/components/schemas/Accounttypes'
 */

额外排查方向 #

• 升级swagger-jsdoc到最新稳定版：执行npm update swagger-jsdoc，旧版本可能存在语法兼容性问题。
• 确认OpenAPI版本匹配：在swagger定义中指定openapi: 3.0.0及以上版本，components是OpenAPI 3.x的语法，与2.x版本不兼容。

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