.NET 5 支持 Azure Functions OpenAPI 扩展啦

2022-02-12 22:20:26

今年5月，在 Build大会上，Azure Functions OpenAPI的功能支持（预览版）正式宣布。当时，它最高支持 v3 运行时——.NET Core 3.1 版本。最近，它发布了 .NET 5 隔离工作器支持包作为预览。在这篇文章中，我将回顾如何使用它并将其部署到 Azure。

注意：您可以在此 GitHub 存储库中找到本文中使用的示例代码：https://github.com/justinyoo/azfunc-openapi-dotnet

在 .NET 5 中创建 Azure Functions 应用程序

让我们使用Visual Studio来完成这个练习。在创建应用程序时，使用".NET 5(隔离)"运行时和"Http触发器"。

然后您将找到带有默认代码的HTTP端点。现在，在解决方案资源管理器上选择NuGet包管理器菜单。

在NuGet包管理器屏幕中，勾选"包括预发布"复选框，然后搜索Microsoft.Azure.Functions.Worker.Extensions.OpenApi包。在撰写本文时，NuGet打包程序版本是v0.8.1-preview。

OpenAPI扩展现在已经安装。

配置 HostBuilder

安装OpenAPI扩展之后，让我们配置HostBuilder。首先，打开Program.cs文件并删除现有的ConfigureFunctionsWorkerDefaults()方法。这是因为该方法默认使用System.Text.Json，我们不会使用它。

 public static void Main(){
        var host = new HostBuilder()
            // ?????????? 删除以下这行 ??????????
            .ConfigureFunctionsWorkerDefaults()
            // ?????????? 删除以上这行 ??????????
            .Build(); 
        host.Run();
    }

然后，按此顺序添加ConfigureFunctionsWorkerDefaults(worker => worker. usenewtonsoftjson())和ConfigureOpenApi()方法。第一个方法明确声明要使用Newtonsoft.Json包，下一个导入额外的OpenAPI相关端点。

public static void Main() 
{
        var host = new HostBuilder()
            // ?????????? Add these lines below ??????????
            .ConfigureFunctionsWorkerDefaults(worker => worker.UseNewtonsoftJson())
            .ConfigureOpenApi()
           // ?????????? Add these lines above ??????????
           .Build();
        host.Run();
}

注意：目前，使用 System.Text.Json 并不能保证应用程序是否正常工作。因此，强烈推荐使用 Newtonsoft.Json。

至此，配置完毕。让我们继续。

添加 OpenAPI 修饰符

添加 OpenAPI 相关的修饰符，如下所示。这与现有方法完全相同，所以我不会讲得太深。

// ?????????? 在下面添加OpenAPI 相关的修饰符??????????
    [OpenApiOperation(operationId: "greeting", tags: new[] { "greeting" }, Summary = "Greetings", Description = "This shows a welcome message.", Visibility = OpenApiVisibilityType.Important)]
    [OpenApiSecurity("function_key", SecuritySchemeType.ApiKey, Name = "code", In = OpenApiSecurityLocationType.Query)]
    [OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "text/plain", bodyType: typeof(string), Summary = "The response", Description = "This returns the response")]
    // ?????????? 在上面添加OpenAPI 相关的修饰符 ??????????
    [Function("Function1")]
    public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequestData req,
        FunctionContext executionContext)
    {
        ...
    }

一旦你完成了修饰符的添加，你就完成了!让我们运行这个应用程序。

运行 Swagger UI

通过输入 F5 键或单击 Visual Studio上的调试按钮运行Function应用程序。

您将看到控制台中添加了OpenAPI相关的端点。

在web浏览器上运行http://localhost:7071/api/swagger/ui端点，您将看到Swagger UI页面。

现在已正确实施具有 OpenAPI 功能的 Azure Function 应用。

部署 Azure Function App – Windows

你确认你的 Azure Function 应用工作正常。现在需要部署该项目。首先，单击解决方案资源管理器中的"发布"菜单。

选择"Azure"，然后选择"Azure Functions App (Windows)"。

您可以使用现有的 Function 应用程序实例或通过单击 ? 按钮来创建一个新的应用程序实例。这一次，让我们使用当前实例。

一旦部署完成，在web浏览器上打开Azure Functions URL，你就会看到Swagger UI页面。

部署 Azure Function 应用 - Linux

这一次，让我们将相同的应用程序部署到Linux实例。除此之外，让我们使用GitHub Actions。为了做到这一点，你必须将这个应用程序上传到GitHub存储库。因此，移动到"Git Changes"窗格并创建一个Git仓库。

如果你已经在Visual Studio中登录了GitHub，你就可以创建一个存储库并推送代码。

一旦推送了所有代码，请访问 GitHub 以检查您的存储库是否已实际上传所有代码。

让我们回到发布屏幕，点击"? New"按钮来创建一个新的发布配置文件。

然后会出现一个类似的弹出窗口。这次让我们使用"Azure Function App (Linux)"菜单。

如前所述，您可以使用现有的实例或创建新的实例。我们就用现有的吧。

在前面的部署练习中，我们没有GitHub存储库。因此，我们不得不使用本地部署的方法。但这一次，我们有GitHub存储库，这意味着我们有选择。因此，这次我们不选择相同的部署方法，而是选择GitHub Actions。

GitHub Actions 工作流现已自动生成。但这需要一个新的commit。

移至"Git Changes"窗格，输入如下所示的提交消息，单击"Commit All"按钮，然后推送更改。

当您实际访问您的 GitHub 存储库时，您的 GitHub 操作工作流会运行buil和部署。

一旦部署结束，打开一个新的web浏览器，访问Azure Functions应用程序URL，并发现Swagger UI页面被正确地呈现。

到目前为止，我们已经学习了如何创建一个支持 OpenAPI的Azure Functions应用程序，在.Net 5独立的工作环境中运行，并无需离开Visual Studio就将其部署到Azure。我猜理论上它也可以在。Net 6上很好运行。如果你好奇，请部署它，并在https://github.com/Azure/azure-functions-openapi-extension/issues上告诉我们！

参考资料

Github 存储库: Azure Functions OpenAPI扩展
Microsoft 文档:在Visual Studio中使用Azure Function和API管理集成创建无服务器API(预览版)
Microsoft学习平台: Azure Functions: 发现OpenAPI和Power应用