Swagger生成API文档时OpenAPI 3.0.0报错：Cannot read property 'get' of undefined

你遇到的问题核心是混用了Swagger 2.0的注解语法和OpenAPI 3.0的规范，swagger-jsdoc在解析这种不匹配的语法时抛出了错误。下面是具体的解决步骤：

1. 确保使用兼容OpenAPI 3.0的swagger-jsdoc版本 #

首先检查你的swagger-jsdoc版本，v4及以上才支持OpenAPI 3.x规范。如果版本过低，先升级：

npm install swagger-jsdoc@latest --save

2. 修正路由中的Swagger注解为OpenAPI 3.0语法 #

你的路由代码里用的是Swagger 2.0的definition和parameters.in: body写法，这在OpenAPI 3.0中已经被替代，需要改成以下格式：

修改后的user路由代码： #

const express = require('express');
const router = express.Router();
const controller = require('../../controllers/v1/user-controller');

/**
 * @swagger
 * components:
 *   schemas:
 *     LoginRequest:
 *       type: object
 *       required:
 *         - username
 *         - password
 *       properties:
 *         username:
 *           type: string
 *         password:
 *           type: string
 */

/**
 * @swagger
 * /user/login:
 *   post:
 *     tags:
 *       - User
 *     summary: User login
 *     description: Authenticate user and return token
 *     requestBody:
 *       required: true
 *       content:
 *         application/x-www-form-urlencoded:
 *           schema:
 *             $ref: '#/components/schemas/LoginRequest'
 *     parameters:
 *       - name: version
 *         in: header
 *         required: true
 *         description: System version
 *         schema:
 *           type: string
 *     responses:
 *       200:
 *         description: Successfully authenticated, returns token
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 token:
 *                   type: string
 *       400:
 *         description: Invalid credentials
 */
router.post('/login', controller.login);

关键修改点：

• 把Swagger 2.0的definition替换成OpenAPI 3.0的components.schemas
• 将parameters.in: body替换为requestBody，并明确指定content类型
• 为每个参数（包括header参数）添加schema定义（OpenAPI 3.0要求）

3. 调整swaggerDefinition的结构（可选但推荐） #

虽然你的app.js里的swaggerDefinition基本正确，但可以调整为更贴合OpenAPI 3.0的标准写法：

const swaggerOptions = {
  swaggerDefinition: {
    openapi: "3.0.0", // 必须放在顶层位置
    info: {
      title: 'Ágil API',
      version: '1.0.0',
      description: 'Document API with autogenerated swagger doc',
    },
    servers: [ // OpenAPI 3.0用servers替代原有的host+basePath
      {
        url: 'http://localhost:3000/',
        description: 'Local development server'
      }
    ],
    components: {
      securitySchemes: {
        BasicAuth: { 
          type: "http", 
          scheme: "basic" 
        }
      }
    },
    security: [ // 格式改为数组包裹的对象
      {
        BasicAuth: []
      }
    ]
  },
  apis: ['./routes/v1/user.js'],
}

完成以上修改后，重启你的Express服务，应该就能正常加载Swagger UI，不会再出现"Cannot read property 'get' of undefined"的错误了。

内容的提问来源于stack exchange，提问作者Guilherme Monteiro de Oliveira