今年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上告訴我們！
參考資料
-
Github 存儲庫: Azure Functions OpenAPI擴展
-
Microsoft 文檔:在Visual Studio中使用Azure Function和API管理集成創建無服務器API(預覽版)
-
Microsoft學習平台: Azure Functions: 發現OpenAPI和Power應用