Serverless Express API无法生成Swagger UI问题求助

以下是几个常见的排查和修复方向，按优先级尝试：

1. 确保Serverless配置捕获所有子路径 #

Serverless框架的API Gateway默认只会映射根路径请求，Swagger UI需要加载/css、/js等静态资源，这些都属于/swagger下的子路径，必须让API Gateway把所有请求转发到Lambda。

修改你的serverless.yml中函数的events配置，添加/{proxy+}通配路径：

functions:
  app:
    handler: src/handler.handler  # 路径需和你的项目结构匹配
    events:
      - http: ANY /
      - http: ANY /{proxy+}  # 这行是关键，捕获所有子路径请求

2. 修正Swagger文档的路径配置 #

你当前配置里的url: "api-docs"是相对路径，在API Gateway环境下可能无法正确指向文档接口。建议单独暴露swagger.json接口，确保文档能被访问：

在handler.ts中添加路由返回Swagger文档：

// 在app.use('/swagger', ...)之前添加
app.get('/swagger/api-docs', (req, res) => {
  res.json(swaggerDocs);
});

// 修改Swagger UI的setup配置
app.use('/swagger', swaggerUi.serve, swaggerUi.setup(swaggerDocs, {
  swaggerOptions: {
    url: '/swagger/api-docs'  // 改为完整相对路径
  },
}));

3. 调整Swagger的API文件路径 #

你的swaggerOptions里配置的apis: ["./routes/*.ts"]针对的是TS源文件，但部署到Lambda的是编译后的JS文件，swagger-jsdoc找不到TS文件就无法生成正确文档，进而导致UI加载失败。

修改apis路径为编译后的JS文件路径：

const swaggerOptions = {
  swaggerDefinition: {
    version: "1.0.0",
    title: "User service",
    description: "user service APIs",
    contact: {
      name: "Sid"
    }
  },
  apis: ["./routes/*.js"]  // 改为JS文件路径，若编译后有单独dist目录，需调整为dist/routes/*.js
};

4. 确认访问路径包含API Gateway阶段前缀 #

如果部署时使用了自定义阶段（比如dev、prod），访问Swagger UI的完整路径需要包含阶段名，格式为：
https://{api-id}.execute-api.{region}.amazonaws.com/{stage}/swagger
别直接访问根域名下的/swagger，会出现404。

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