使用serverless-auto-swagger生成Swagger文档时加载失败求助

你在使用serverless-auto-swagger插件为TypeScript编写的Serverless Express API生成Swagger文档时，已完成依赖安装和插件配置，但启动离线服务器后访问Swagger页面出现错误：无法加载API定义。获取错误：未找到 http://localhost:3000/dev/swagger/.json

以下是针对性的解决步骤：

• 补充serverless.yml的swagger自定义配置
  serverless-auto-swagger需要明确配置类型文件路径等参数才能生成文档，在配置文件中添加：

  custom:
    serverless-auto-swagger:
      generateSwaggerOnDeploy: true
      typefiles: ['./src/**/*.ts'] # 指向你的TS类型定义文件所在路径
      swaggerPath: 'swagger'
  

  注意typefiles必须覆盖包含API接口类型的文件，这是插件生成Swagger JSON的核心依据。

• 手动预先生成Swagger文档
  先单独执行生成命令，再启动离线服务，验证文档是否正常生成：

  serverless swagger generate
  serverless offline start
  

  执行后检查项目根目录下是否出现.swagger文件夹，里面应有swagger.json文件。

• 确认阶段与路由配置正确性
  确保启动离线服务时指定的阶段与URL中的dev一致，可显式指定：

  serverless offline start --stage dev
  

  同时检查functions下的http事件配置，确保path和method定义清晰，插件需要识别这些事件来关联文档。

• 检查插件兼容性并更新
  不同版本的serverless-auto-swagger与serverless-offline可能存在兼容问题，更新到最新版本尝试：

  npm update -D serverless-auto-swagger serverless-offline
  

• 验证Express Handler的集成方式
  确保你的Express应用通过serverless-http正确包装导出，示例如下：

  // src/handler.ts
  import serverless from 'serverless-http';
  import express from 'express';
  
  const app = express();
  
  app.get('/basket/:basketId', (req, res) => {
    // 业务逻辑
    res.json({ basketId: req.params.basketId });
  });
  
  export const handler = serverless(app);
  

  插件需要识别Express路由结构来生成对应Swagger接口定义。

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