.NET 5 Support of Azure Functions OpenAPI Extension

This post has been republished via RSS; it originally appeared at: New blog articles in Microsoft Tech Community.

In May this year at //Build, Azure Functions OpenAPI support feature (preview) was officially announced. At that time, it supported up to the v3 runtime – .NET Core 3.1 version. Recently, it has released .NET 5 isolated worker supporting package as a preview. Throughout this post, I'm going to review how to use it and deploy it to Azure.

 

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

 

Creating Azure Functions App in .NET 5

 

Let's use Visual Studio for this exercise. While creating the app, use the ".NET 5 (Isolated)" runtime and "Http trigger".

 

Choose .NET 5 (Isolated) then Http trigger

 

Then you'll find out the HTTP endpoint with default codes. Now, select the NuGet Package Manager menu at Solution Explorer.

 

Select NuGet Package Manager menu

 

In the NuGet Package Manager screen, tick the "Include prerelease" checkbox and search up the Microsoft.Azure.Functions.Worker.Extensions.OpenApi package. As of this writing, the NuGet packager version is v0.8.1-preview.

 

Search up the OpenAPI extension in the NuGet Package Manager screen

 

OpenAPI extension has now been installed.

 

Configuring HostBuilder

 

After installing the OpenAPI extension, let's configure the HostBuilder. First, open the Program.cs file and remove the existing ConfigureFunctionsWorkerDefaults() method. It's because this method uses System.Text.Json by default, which we're not going to use.

 

    public static void Main()
    {
        var host = new HostBuilder()
            // πŸ‘‡πŸ‘‡πŸ‘‡πŸ‘‡πŸ‘‡ Remove this line below πŸ‘‡πŸ‘‡πŸ‘‡πŸ‘‡πŸ‘‡
            .ConfigureFunctionsWorkerDefaults()
            // πŸ‘†πŸ‘†πŸ‘†πŸ‘†πŸ‘† Remove this line above πŸ‘†πŸ‘†πŸ‘†πŸ‘†πŸ‘†
            .Build();
    
        host.Run();
    }

 

Then, add both ConfigureFunctionsWorkerDefaults(worker => worker.UseNewtonsoftJson()) and ConfigureOpenApi() method in this order. The first method explicitly declares to use the Newtonsoft.Json package and the next one imports the 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 doesn't guarantee whether the app works appropriately or not. Therefore, Newtonsoft.Json is highly recommended.

 

Now, the configuration is over. Let's move on.

 

Adding OpenAPI Decorators

 

Add OpenAPI related decorators like below. It's precisely the same exercise as the existing approach, so I'm not going too deep.

 

    // πŸ‘‡πŸ‘‡πŸ‘‡πŸ‘‡πŸ‘‡ Add OpenAPI related decorators below πŸ‘‡πŸ‘‡πŸ‘‡πŸ‘‡πŸ‘‡
    [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")]
    // πŸ‘†πŸ‘†πŸ‘†πŸ‘†πŸ‘† Add OpenAPI related decorators above πŸ‘†πŸ‘†πŸ‘†πŸ‘†πŸ‘†
    
    [Function("Function1")]
    public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequestData req,
        FunctionContext executionContext)
    {
        ...
    }

 

Once you complete adding the decorators, you're all done! Let's run the app.

 

Running Swagger UI

 

Run the Function app by entering the F5 key or clicking the debug button on Visual Studio.

 

Run Azure Function app with the debug mode

 

You'll see the OpenAPI related endpoints added in the console.

 

OpenAPI related endpoints added

 

Run the http://localhost:7071/api/swagger/ui endpoint on your web browser, and you'll see the Swagger UI page.

 

Swagger UI page

 

Your Azure Function app with OpenAPI capability has now been implemented correctly.

 

Deploying Azure Function App – Windows

 

You confirmed that your Azure Function app is working fine. It's time for deployment. First of all, click the "Publish" menu at Solution Explorer.

 

Azure Functions publish menu

 

Choose "Azure", followed by "Azure Functions App (Windows)".

 

Choose deployment method for Windows

 

You can use the existing Function app instance or create a new one by clicking the :heavy_plus_sign: button. This time, let's use the current instance.

 

Choose existing instance

 

Once deployment is done, open the Azure Functions URL on your web browser, and you'll see the Swagger UI page.

 

Swagger UI on Azure

 

Deploying Azure Function App – Linux

 

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

 

Git Changes pane

 

If you've already logged in to GitHub within Visual Studio, you'll be able to create a repository and push the codes.

 

Create GitHub repository

 

Once pushed all codes, visit GitHub to check your repository whether all codes have actually been uploaded.

 

Complete creating GitHub repository

 

Let's go back to the publish screen and click the ":heavy_plus_sign: New" button to create a new publish profile.

 

New publish profile

 

Then a similar pop-up appears to before. This time let's use the "Azure Function App (Linux)" menu.

 

Choose the deployment method for Linux

 

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

 

Choose existing instance

 

In the previous deployment exercise, we haven't got a GitHub repository. Therefore, we had to use the local deployment method. But this time, we've got the GitHub repository, meaning we've got choices. Therefore, instead of choosing the same deployment method, let's choose GitHub Actions for this time.

 

Choose GitHub Actions

 

GitHub Actions workflow has now been automatically generated. But this needs a new commit.

 

GitHub Actions commit & push

 

Move to the "Git Changes" pane, enter the commit message like below, click the "Commit All" button, and push the change.

 

Commit & push the GitHub Actions workflow

 

When you actually visit your GitHub repository, your GitHub Actions workflow runs the build and deployment.

 

Deploying Function app with GitHub Actions

 

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

 

Swagger UI on Azure

 


 

So far, we've walked through how to create an OpenAPI enabled Azure Functions app, running on .NET 5 isolated worker environment, and deploy it to Azure without having to leave Visual Studio. I'm guessing that it will run OK on .NET 6, theoretically. If you're curious, please deploy it and let us know at https://github.com/Azure/azure-functions-openapi-extension/issues!

 

Call to Action

 

 


 

This article was originally published on Dev Kimchi.

Leave a Reply

Your email address will not be published. Required fields are marked *

*

This site uses Akismet to reduce spam. Learn how your comment data is processed.