部署带swagger-ui-express的Express API到AWS Lambda后Swagger文档无法访问

问题核心是swagger-ui-express默认重定向路径未携带API Gateway的阶段前缀（如dev），导致访问/dev/docs时自动跳转到/docs触发403。以下是具体解决步骤：

1. 配置Swagger文档的Base路径 #

在Swagger定义文件（如swagger.json）中添加servers字段指定阶段前缀，确保Swagger UI生成的接口请求路径正确：

{
  "openapi": "3.0.0",
  "info": { ... },
  "servers": [
    {
      "url": "/dev"
    }
  ],
  "paths": { ... }
}

如果需要兼容本地和部署环境，可通过代码动态生成servers配置，读取环境变量中的阶段名：

const stage = process.env.STAGE || 'dev';
swaggerDocument.servers = [{ url: `/${stage}` }];

2. 初始化Swagger UI时指定BasePath #

在Express应用挂载swagger-ui-express时，通过swaggerOptions明确设置basePath，避免重定向丢失阶段前缀：

const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

const stage = process.env.STAGE || 'dev';
const swaggerOptions = {
  swaggerOptions: {
    basePath: `/${stage}`
  }
};

// 挂载时使用带阶段前缀的路径
app.use(`/${stage}/docs`, swaggerUi.serve, swaggerUi.setup(swaggerDocument, swaggerOptions));

3. 验证API Gateway Proxy配置 #

确保API Gateway的{proxy+}资源配置无误：

• 资源路径设置为/{proxy+}
• 已启用Lambda代理集成
• 方法请求允许GET方法访问/docs相关路径
• 阶段部署的路径前缀（dev）已正确关联到Lambda集成

完成以上配置后，访问/dev/docs时Swagger UI会正确保留阶段前缀，不会跳转到根路径的/docs，即可正常加载接口文档。

内容的提问来源于stack exchange，提问作者Juan Pablo Betancourt