使用Swagger文档化TypeScript转译API时端点不显示求助

1. 修正apis路径配置 #

TypeScript转译后文件存放在dist目录，运行时的代码入口位于dist下，原配置的相对路径./routes/*.js会基于当前运行的模块目录（即dist）查找文件，若转译后的路由文件在dist/routes/下，需调整路径确保能匹配到目标文件：

方案：使用绝对路径（推荐） #

通过path模块拼接绝对路径，避免相对路径的工作目录依赖问题：

import path from 'path';

export const options = {
    swaggerDefinition: {
      openapi: '3.0.0',
      info: {
        title: 'MEnvio API',
        version: '1.0.0',
        description: 'Doumentación de los enpoints de la API del Backend del sistema MIEnvio',
      },
      servers: [
        {
          url: 'http://localhost:1802',
        },
      ],
    },
    apis: [path.join(__dirname, './routes/*.js')],
};

2. 修正Swagger注释的路径与格式 #

路径匹配问题 #

你的路由挂载在${process.env.USERSROUTE}前缀下（例如/api/users），但注释中仅写了相对路径/getDataUser，导致Swagger识别的路径与实际接口路径不符。可通过两种方式修正：

• 方式1：注释中写完整路径

/**
* @swagger
* /api/users/getDataUser/{id}:
*  get:
*    summary: 获取用户数据
*    parameters:
*      - in: path
*        name: id
*        required: true
*        schema:
*          type: string
*        description: 用户ID
*    responses:
*      200:
*        description: 成功返回用户数据
*/
this.router.get('/getDataUser/:id', this.controller.getUserData);

• 方式2：在swaggerDefinition中配置basePath

swaggerDefinition: {
  openapi: '3.0.0',
  info: { /* 原有配置 */ },
  servers: [ /* 原有配置 */ ],
  basePath: process.env.USERSROUTE // 例如'/api/users'
},

此时注释中可写相对路径/getDataUser/{id}，Swagger会自动拼接basePath。

注释格式规范 #

确保注释符合OpenAPI 3.0语法：

• @swagger标记后内容缩进正确
• 路径参数（如:id）需用{id}包裹并在parameters字段中定义
• 必要字段（如summary、responses）不可缺失，否则注释可能不被识别

3. 检查转译时的注释保留设置 #

若tsconfig.json中开启了removeComments: true，转译后的JS文件会丢失Swagger注释，导致swagger-jsdoc无法读取。需修改配置：

{
  "compilerOptions": {
    "removeComments": false
  }
}

4. 验证specs生成结果 #

查看config()方法中console.log(specs)的输出：

• 若specs中无paths字段：说明apis路径配置错误，未找到包含注释的路由文件
• 若paths字段为空：说明路径正确但注释格式不符合规范，需逐行检查注释语法

内容的提问来源于stack exchange，提问作者sergio daniel baron cabrera