Express Node.js集成Swagger后API调用返回404错误求助

排查与解决步骤 #

• 核对路由路径与Swagger注释的一致性
  先确认你的Express代码里实际注册的接口路径，和@swagger注释里的path字段完全匹配。比如注释写的是/first，就得保证代码里是app.get('/first', ...)；如果接口统一挂了/api这类前缀，那Swagger注释里的路径也要改成/api/first，或者在Swagger配置里加basePath统一指定前缀。
• 检查Swagger的basePath配置
  要是你的API有全局前缀（比如/api/v1），必须在Swagger的definition里加上basePath: '/api/v1'，不然Swagger UI发起请求时会直接用注释里的短路径，和实际接口路径不匹配，自然返回404。
• 确认API文件是否被正确加载
  去server.js里检查，有没有正确引入那几个API文件，并且把路由挂载到Express应用上。比如有没有漏写require('./modules/data/first.js')，或者挂载路由的代码是不是写错了。
• 验证请求方法是否匹配
  比如Swagger注释里写的是get请求，但实际接口是post，或者反过来，这种方法不匹配的情况也会返回404，得仔细核对每个接口的HTTP方法。
• 查看完整请求URL
  在Swagger UI的请求面板里看发起请求的完整地址，对比你的应用实际监听的端口、域名，确认没有前缀或者地址的差异。

示例修正参考 #

如果你的API都挂在/api前缀下，Swagger配置要改成这样：

const swaggerJsdoc = require('swagger-jsdoc');
const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: '你的API服务',
      version: '1.0.0',
    },
    basePath: '/api', // 添加上实际的API前缀
  },
  apis: ["./modules/data/first.js", "./modules/second.js", "./modules/config/getConfig.js"],
};
const swaggerSpec = swaggerJsdoc(options);

对应的路由注册也要带前缀：

// first.js 里的路由代码
const express = require('express');
const router = express.Router();
router.get('/first', (req, res) => {
  res.send('First接口响应');
});
module.exports = router;

// server.js 里挂载路由
const firstRouter = require('./modules/data/first.js');
app.use('/api', firstRouter);

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