.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 πŸ‘‡πŸ‘‡πŸ‘‡πŸ‘‡πŸ‘‡
            // πŸ‘†πŸ‘†πŸ‘†πŸ‘†πŸ‘† Remove this line above πŸ‘†πŸ‘†πŸ‘†πŸ‘†πŸ‘†


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())
            // πŸ‘†πŸ‘†πŸ‘†πŸ‘†πŸ‘† Add these lines above πŸ‘†πŸ‘†πŸ‘†πŸ‘†πŸ‘†


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 πŸ‘†πŸ‘†πŸ‘†πŸ‘†πŸ‘†
    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.

REMEMBER: these articles are REPUBLISHED. Your best bet to get a reply is to follow the link at the top of the post to the ORIGINAL post! BUT you're more than welcome to start discussions here:

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