.NET 5 supports Azure Functions OpenAPI extension!

We are happy to announce that .NET 5 supports the Azure Functions OpenAPI extension!

In May of this year, at the Build conference, the feature support (preview version) of Azure Functions OpenAPI was 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:

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: At present, using System.Text.Json does not guarantee whether the application works normally. Therefore, it is strongly recommended to use Newtonsoft.Json.

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

Add OpenAPI modifier

// 👇👇👇👇👇 在下面添加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 the debug button on 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, UI page.

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

Deploy Azure Fuuction APP-Windows

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

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

You can use an existing Function application instance or create a new application instance by clicking the :heavy_plus_sign: button. 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. So, move to the "Git Changes" pane and create a Git repository.

If you are already logged into GitHub in Visual Studio, you can create a repository and push 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 an Azure Functions application that supports OpenAPI, run in a .Net 5 isolated work environment, and deploy it to Azure without leaving Visual Studio. I guess it can also run well on .Net 6 in theory. If you are curious, please deploy it and let us know

Reference

Enter GitHub search: Azure Functions OpenAPI extension
Enter the Microsoft Docs search: Use Azure Function and API management integration to create a serverless API in Visual Studio (Preview)
Enter MS Learn platform search: Azure Functions: Discover OpenAPI and Power applications

Reference link