今年5月，在 Build大會上，Azure FunctionsOpenAPI的功能支援（預覽版）正式宣佈。 當時，它最高支援 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上告訴我們！

參考資料