Azure Functions V2 中的 OpenAPI(又名 Swagger)

OpenAPI (aka Swagger) in Azure Functions V2

我正在创建一个 V2 函数应用程序并希望将 Swagger/Open API 用于文档,但它在 Azure 门户中尚不支持 V2 函数。

关于如何在 VSTS 中使用带有 V2 函数的 Swagger 在每个构建上创建文档的任何建议?

您能否通过先使用空白函数应用程序重新开始,在 运行 时间的 v1 上将 V2 函数降为 运行?

Create an OpenAPI definition for a function 的 MSDN 文档(有趣的是日期为 11/2018)示例指出:

By default, the function app you create uses version 2.x of the runtime. You must set the runtime version back to 1.x before you create your function.

但不能只将设置移动到 1:

To pin your function app to the version 1.x runtime, choose ~1 under Runtime version. This switch is disabled when you have functions in your app.

这意味着必须创建函数应用程序,publish/create它,将其设置为 V1,然后在添加函数应用程序之前放入一个函数。

TL;DR - 使用 NuGet 包通过 Azure Functions 呈现 Open API 文档和 Swagger UI。


更新 (2021-06-04)

Microsoft 最近 announced the OpenAPI support on Azure Functions 在 //Build 活动期间。

Aliencube 扩展现已存档,不再受支持。请使用这个 official extension.

截至今天,它处于预览状态。虽然它是预览版,但它比 Aliencube 的功能更多。

Acknowledgement 2: I am still maintaining the official one.


Microsoft 尚未正式开始支持 Open API(或 Swagger)。但是目前有一个社区驱动的 NuGet 包可用:

Nuget > Aliencube.AzureFunctions.Extensions.OpenApi

这里是博客post:

Introducing Swagger UI on Azure Functions

基本上它的用法类似于Swashbuckle——使用装饰器。并且它同时支持 Azure Functions V1 和 V2。

Acknowledgement 1: I am the owner of the NuGet package.

对于任何对此进行研究的人,Microsoft 仍未添加对 Azure Functions +v2 的 Open API 支持,也没有任何重大进展。

我最近遇到了同样的问题,我找到了一个很好的解决方案。 如果您还不知道,请查看:https://github.com/RicoSuter/NSwag

NSwag 是一个工具链,它与 .NET 集成以生成 Open API 文档和 UI,但也会为您生成相应的 API 客户端。 我在过去 2 年中使用此工具来处理 Angular 和 .NET 应用程序,它节省了大量时间并与我的整个开发工作流程无缝集成。

对于 Azure Functions +v2,贡献者创建了一个生成器,它用不到 10 行代码,允许我们公开 Azure Functions class 的 Swagger 端点: https://github.com/Jusas/NSwag.AzureFunctionsV2

现在,如果您使用 DI 设计 HTTP-Triggered 函数,将相关操作分组在同一个 class 下并利用模型绑定,您甚至可能不需要应用任何自定义装饰器,它就可以了! 这是一个真实的 API 的示例:

(忽略基数 class。这是我遵循的个人模式的一部分,与 Swagger 无关)

这就是使用 swagger 的样子 UI:

官方图书馆Azure Functions OpenAPI Extension。它仍在预览,但看起来很棒。