使用Koa注解配置Swagger却无法显示接口文档的问题

看起来你遇到的问题是Swagger没有正确识别你在登录接口上写的注解，我帮你梳理下几个关键的错误点和修复方案：

1. Swagger注解语法不符合OpenAPI 3.0规范 #

你的注解里有两个核心问题，直接导致Swagger无法解析：

• 参数块位置错误：你把parameters写在了post方法的外面，这完全不符合Swagger的结构规范，所有属于POST请求的配置都要放在post节点内部。
• 混用旧版语法+参数定义错误：OpenAPI 3.0已经废弃了in: body的写法，需要用requestBody来包裹请求体参数；而且你定义password参数时写错了格式，应该是- name: password而不是- password: password。

下面是修正后的登录接口注解代码：

/**
 * @swagger
 * /login:
 *    post:
 *      description: User Login
 *      requestBody:
 *        required: true
 *        content:
 *          application/json:
 *            schema:
 *              type: object
 *              required:
 *                - username
 *                - password
 *                - code
 *              properties:
 *                username:
 *                  type: string
 *                  description: User's login username
 *                password:
 *                  type: string
 *                  description: User's login password
 *                code:
 *                  type: string
 *                  description: Captcha verification code
 *      responses:
 *        '200':
 *          description: Successfully logged in, returns JWT token
 *          content:
 *            application/json:
 *              schema:
 *                type: object
 *                properties:
 *                  token:
 *                    type: string
 *        '400':
 *          description: Bad request (invalid username/password or captcha)
 *        '500':
 *          description: Server internal error
 */
loginRouter.post('/', verifyLogin, verifyCaptcha, LoginController.generateToken)

2. 检查swagger-jsdoc的文件匹配配置 #

在swagger.ts里，你配置的apis: [path.join(__dirname, '../router/*.ts')]可能存在路径匹配问题：

• 确认你的目录结构是否正确，比如__dirname对应的是当前swagger.ts所在的目录，../router/*.ts是否能准确找到所有路由文件。如果路由文件有子目录，可以改成../router/**/*.ts来递归匹配。
• 可以临时在swagger.ts里打印一下匹配的路径，确认是否正确：

  const apiPaths = path.join(__dirname, '../router/*.ts');
  console.log('Swagger scanning paths:', apiPaths);
  

3. 调试生成的Swagger文档 #

在swagger.ts里，你可以打印出生成的swaggerDocs内容，确认是否包含了登录接口的定义：

const swaggerDocs = swaggerJsdoc(options);
// 打印生成的文档结构，方便调试
console.log('Generated Swagger Document:', JSON.stringify(swaggerDocs, null, 2));

如果打印结果里没有/login的接口信息，那要么是路径匹配没找到文件，要么是注解语法还有问题；如果有，那就是Swagger UI的配置问题（这种情况很少见）。

按照上面的步骤修改后，重启你的Koa服务，再访问/api/docs，应该就能看到正确的登录接口文档了，包括请求体参数和响应定义。

备注：内容来源于stack exchange，提问作者Linda Smith