如何在Middy框架中使用Swagger并实现接口文档自动生成

原生实现方案 #

Middy 官方提供了配套的OpenAPI生成能力，不需要手动从零搭建生成逻辑：

• 安装@middy/openapi中间件，建议搭配@middy/validator请求校验中间件共同使用，你编写的接口入参校验Schema可以直接复用到OpenAPI文档的字段定义中
• 在中间件配置项中补充接口的请求方法、路径、出参结构、错误码说明等元信息，部署或者本地启动时会自动聚合所有路由的配置，生成符合Swagger规范的OpenAPI 3.0文件
  注意尽量复用同一套Schema作为校验和文档的数据源，避免出现文档和实际接口逻辑不一致的问题

你提到的替代方案优化建议 #

你构思的“生成Swagger文件+Lambda承载Swagger UI”的方案完全可以落地，还可以做以下优化：

• 生成Swagger文件环节可以直接复用上述@middy/openapi中间件的输出结果，不需要单独开发代码解析接口逻辑
• 承载Swagger UI的Lambda可以额外暴露一个/openapi.json接口，动态返回最新的接口规范内容，Swagger UI配置为从该接口拉取配置，后续更新接口不需要重新部署UI相关的静态资源

本地调试技巧 #

本地开发阶段可以搭配serverless-offline插件，直接在本地环境预览生成的接口文档，不需要部署到云端就能验证配置是否正确。

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