Node.js版Azure Function如何添加Open API规范生成Swagger文档？

同类功能包说明 #

目前微软官方没有推出和.NET版Microsoft.Azure.WebJobs.Extensions.OpenApi完全对应的Node.js版官方扩展包，不过有多个社区维护的第三方包可以实现同类能力：

• azure-functions-openapi-extension：用法逻辑和.NET官方扩展接近，通过给Function导出配置添加OpenAPI相关注解，即可自动生成规范文档和Swagger UI页面，支持OpenAPI 3.0规范，可配置请求参数、响应结构、认证规则等常用字段。
• swagger-azure-functions：轻量型工具，仅需提前准备好YAML/JSON格式的OpenAPI规范，就能一键挂载到Azure Function的HTTP端点对外暴露Swagger UI，不需要修改原有业务代码。

无第三方依赖的替代方案 #

如果不想引入第三方社区包，也可以通过以下方案实现接口文档生成：

• 手动维护规范+静态挂载：先按照OpenAPI 3.0规范编写对应接口的swagger.json或swagger.yaml文件，存到Function App的静态资源目录；新增一个路径为/swagger/ui的HTTP触发Function，返回嵌入Swagger UI的静态HTML页面，关联你本地存放的规范文件即可。该方案灵活性最高，无额外依赖，适合接口数量较少、变动频率低的场景。
• 代码注解自动生成：使用swagger-jsdoc库，给每个Function的业务代码添加JSDoc注解，标注接口地址、请求参数、响应结构、错误码等信息，在项目构建阶段自动生成完整的OpenAPI规范文件，再按照上述方法挂载Swagger UI即可。该方案注解和业务代码同步维护，避免文档和实际接口不一致的问题，适合接口迭代频繁的项目。
• 对接Azure API Management生成：如果你的Azure Function已经接入了Azure API Management（APIM），可以直接将Function端点导入APIM，在APIM控制台补充接口的请求、响应、认证等配置，由APIM直接对外提供OpenAPI规范和接口文档页面，不需要修改Function本身的业务代码。

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