Node.js Swagger 2.0部署ByteNote服务器后无API操作定义求助

本地运行时Swagger API文档可正常显示，但部署到ByteNote服务器后，__dirname指向app/dist，Swagger界面提示No operations defined in spec! on dist，无法正常展示API文档。

配置代码 #

const swaggerDocOptions = {
  explorer: true,
  definition: {
    swagger: '2.0',
    components: {},
    info: {
      title: 'Document API',
      version: '1.0.0',
      description: 'document API',
    },
    schemes: [
      'http',
      'https',
    ],
    security: [{
      simple: [],
    }],
    securityDefinitions: {
      simple: {
        type: 'basic',
      },
    },
  },
  basedir: `${__dirname}`,
  apis: [
    `${__dirname}\\routes\\*.js`,
  ],
};

const specs = swaggerJsDoc(swaggerDocOptions);
app.use('/api-docs', swaggerUI.serve, swaggerUI.setup(specs));

截图说明 #

• 本地正常显示：
• 服务器异常显示：

问题原因及解决方法 #

问题原因 #

1. 跨平台路径分隔符不兼容：代码中硬编码了Windows系统的反斜杠\\，而服务器通常为Linux系统，使用正斜杠/，导致swagger-jsdoc无法匹配到路由文件路径。
2. 构建后文件结构不匹配：部署后__dirname指向app/dist，若构建过程中未正确保留routes目录结构，或路由文件的Swagger注释被编译工具移除，会导致API定义无法被读取。

解决方法 #

1. 使用Node.js内置path模块拼接路径：确保路径在Windows和Linux系统下都能正常解析，修改配置代码如下：

   const path = require('path');
   
   const swaggerDocOptions = {
     explorer: true,
     definition: {
       swagger: '2.0',
       components: {},
       info: {
         title: 'Document API',
         version: '1.0.0',
         description: 'document API',
       },
       schemes: ['http', 'https'],
       security: [{ simple: [] }],
       securityDefinitions: {
         simple: { type: 'basic' }
       }
     },
     basedir: __dirname,
     apis: [path.join(__dirname, 'routes', '*.js')]
   };
   
   const specs = swaggerJsDoc(swaggerDocOptions);
   app.use('/api-docs', swaggerUI.serve, swaggerUI.setup(specs));
   

2. 检查构建后的文件结构：确认app/dist目录下存在routes文件夹，且其中的.js文件保留了完整的Swagger JSDoc注释（如/** @swagger ... */格式的注释块）。
3. 验证编译配置：若为TypeScript项目，确保tsconfig.json中removeComments设为false，避免构建时删除Swagger注释；若使用其他打包工具，需配置保留JSDoc注释。

内容的提问来源于stack exchange，提问作者quoc bao Pham