.NET 5 supports Azure Functions OpenAPI extension

In May of this year, at the Build conference , Azure Functions OpenAPI function support (preview) officially announced . At that time, it supported up to the v3 runtime-.NET Core 3.1 version. Recently, it released the .NET 5 isolation worker support package as a preview. In this article, I will review how to use it and deploy it to Azure.

Note: You can find the sample code used in this article in this GitHub repository: https://github.com/justinyoo/azfunc-openapi-dotnet

Create an Azure Functions application in .NET 5

Let us use Visual Studio to complete this exercise. When creating an application, use ".NET 5 (Isolation)" runtime and "Http trigger".

Then you will find the HTTP endpoint with the default code. Now, select the NuGet Package Manager menu on the Solution Explorer.

In the NuGet package manager screen, check the "Include pre-release" checkbox, and then search for the Microsoft.Azure.Functions.Worker.Extensions.OpenApi package. At the time of writing, the NuGet packager version is v0.8.1-preview.

The OpenAPI extension is now installed.

Configure HostBuilder

After installing the OpenAPI extension, let's configure HostBuilder. First, open the Program.cs file and delete the existing ConfigureFunctionsWorkerDefaults() method. This is because this method uses System.Text.Json by default, and we will not use it.

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

Then, add ConfigureFunctionsWorkerDefaults(worker =\> worker. usenewtonsoftjson()) and ConfigureOpenApi() methods in this order. The first method explicitly declares to use the Newtonsoft.Json package, and the next one imports additional OpenAPI-related endpoints.

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

Note: Currently, using System.Text.Json does not guarantee that the application will work properly. Therefore, it is strongly recommended to use Newtonsoft.Json.

At this point, the configuration is complete. let's continue.

Add OpenAPI modifier

Add OpenAPI-related modifiers, as shown below. This is exactly the same as the existing method, so I won't go into it too deeply.

// 👇👇👇👇👇 在下面添加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)
    {
        ...
    }

Once you have finished adding modifiers, you are done! Let's run the application.

Run Swagger UI

Run the Function application by typing the F5 key or clicking Visual Studio

You will see that OpenAPI-related endpoints have been added to the console.

http://localhost:7071/api/swagger/ui endpoint on a web browser, and you will see the Swagger UI page.

The Azure Function application with OpenAPI function is now correctly implemented.

Deploy Azure Function App-Windows

You confirm that your Azure Function application is working properly. Now you need to deploy the project. First, click the "Publish" menu in the Solution Explorer.

Select "Azure" and then "Azure Functions App (Windows)".

You can use an existing Function application instance or click the :heavy\_plus\_sign: button to create a new application instance. This time, let's use the current instance.

Once the deployment is complete, open the Azure Functions URL on a web browser and you will see the Swagger UI page.

Deploy Azure Function Application-Linux

This time, let's deploy the same application to the Linux instance. Other than that, let's use GitHub Actions. In order to do this, you must upload this application to the GitHub repository. Therefore, move to the "Git Changes" pane and create a Git repository.

If you have Visual Studio , you can create a repository and push the code.

Once all the code has been pushed, please visit GitHub to check if your repository has actually uploaded all the code.

Let's go back to the release screen and click the ":heavy\_plus\_sign: New" button to create a new release profile.

Then a similar pop-up window will appear. Let's use the "Azure Function App (Linux)" menu this time.

As mentioned earlier, you can use an existing instance or create a new instance. Let's use the existing one.

In the previous deployment exercise, we did not have a GitHub repository. Therefore, we have to use the local deployment method. But this time, we have a GitHub repository, which means we have a choice. Therefore, instead of choosing the same deployment method this time, we choose GitHub Actions.

The GitHub Actions workflow is now automatically generated. But this requires a new commit.

Move to the "Git Changes" pane, enter the commit message as shown below, click the "Commit All" button, and then push the changes.

When you actually access your GitHub repository, your GitHub action workflow will run buil and deploy.

Once the deployment is over, open a new web browser, visit the Azure Functions application URL, and find that the Swagger UI page is rendered correctly.

So far, we have learned how to create a support OpenAPI Azure Functions application, run in a .Net 5 independent working environment, and deploy it to Azure Visual Studio I guess it can be in theory too. It runs very well on Net 6. If you are curious, please deploy it and let us know https://github.com/Azure/azure-functions-openapi-extension/issues

Reference

• Github repository: Azure Functions OpenAPI extension
• Microsoft document: API using Azure Function and API management integration in Visual Studio (Preview)
• Microsoft Learning Platform: Azure Functions: Discover OpenAPI and Power applications