Apps on Azure Blog

5 MIN READ

General Availability of Azure Functions OpenAPI Extension

Microsoft

Nov 08, 2021

Exactly a year ago, the first public preview version of Azure Functions OpenAPI Extension was released, which had been a long-waited feature from the dev communities for a long time. Today, we cannot be more excited to announce the general availability of Azure Functions OpenAPI Extension. It was originally a community-driven project, and then it's now become the "official" extension. This extension supports .NET Core 2.1 (LTS), 3.1 (LTS), .NET 5 and .NET 6 (LTS). It also supports both in-process worker and out-of-process worker of Azure Functions runtime. Throughout this post, let's take a look at how to create a function app with the OpenAPI extension in .NET 6, in Visual Studio 2022.

NOTE: The updated Visual Studio project template for this extension supporting both in-process and out-of-process workers is on the way. Please stay tuned.

In-Process Worker

In Visual Studio 2022, you can create a function app in .NET with the in-process worker.

Choose ".NET 6".
Select "Http trigger with OpenAPI" menu on the left-hand side.
Select "Function" for the Authorization level field.
Click the "Create" button.

In-Proc Worker: New Azure Functions Application in .NET 6

You will see the code like below, with several decorators starting with OpenApi (line #7-10).

public class Function1
{
    ...

    [FunctionName("Function1")]

    [OpenApiOperation(operationId: "Run", tags: new[] { "name" })]
    [OpenApiSecurity("function_key", SecuritySchemeType.ApiKey, Name = "code", In = OpenApiSecurityLocationType.Query)]
    [OpenApiParameter(name: "name", In = ParameterLocation.Query, Required = true, Type = typeof(string), Description = "The **Name** parameter")]
    [OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "text/plain", bodyType: typeof(string), Description = "The OK response")]

    public async Task<IActionResult> Run(
        [HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)] HttpRequest req)
    {
        ...
    }
}

Since the updated Visual Studio project template for this extension is on the way, the OpenApi extension needs to be updated for now. Right mouse click on the "Dependencies" menu in Solution Explorer, then click the "Manage NuGet Packages..." menu.

In-Proc Worker: Manage NuGet Packages...

Update the existing Microsoft.Azure.WebJobs.Extensions.OpenApi package version to 1.0.0.

In-Proc Worker: Update NuGet Package

Once updated, rebuild the project and run the function app by clicking the "Debug" button at the top.

In-Proc Worker: Run Function App

Open a web browser and go to http://localhost:7071/api/swagger/ui, and you will see the Swagger UI page as expected.

In-Proc Worker: Swagger UI

Out-of-Process Worker

In Visual Studio 2022, you can also create a function app in .NET with the out-of-process worker. Since the updated Visual Studio project template for this extension is on the way, you need to the existing HTTP trigger and add the NuGet package for now.

Choose ".NET 6 Isolated".
Select "Http trigger" menu on the left-hand side.
Select "Function" for the Authorization level field.
Click the "Create" button.

Out-of-Proc Worker: New Azure Functions Application in .NET 6

You need to add the NuGet package, Microsoft.Azure.Functions.Worker.Extensions.OpenApi from the NuGet Package Manager.

Out-of-Proc Worker: Manage NuGet Packages...

Once installed, update Program.cs to activate the extension. Remove ConfigureFunctionsWorkerDefaults() (line #7) and add ConfigureFunctionsWorkerDefaults(worker => worker.UseNewtonsoftJson()) and ConfigureOpenApi() (line #10-11).

public class Program
{
    public static void Main()
    {
        var host = new HostBuilder()
            // Remove this line
            .ConfigureFunctionsWorkerDefaults()

            // Add these two lines
            .ConfigureFunctionsWorkerDefaults(worker => worker.UseNewtonsoftJson())
            .ConfigureOpenApi()

            .Build();

        host.Run();
    }
}

Then, add the OpenAPI related decorators to the function app endpoint (line #7-9).

public class Function1
{
    ...

    [Function("Function1")]

    [OpenApiOperation(operationId: "Run", tags: new[] { "greetings" })]
    [OpenApiSecurity("function_key", SecuritySchemeType.ApiKey, Name = "code", In = OpenApiSecurityLocationType.Query)]
    [OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "text/plain", bodyType: typeof(string), Description = "The OK response")]

    public HttpResponseData Run([HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequestData req)
    {
        ...
    }
}

Once updated two files like above, rebuild the project and run the function app by clicking the "Debug" button at the top.

Out-of-Proc Worker: Run Function App

Open a web browser and go to http://localhost:7071/api/swagger/ui, and you will see the Swagger UI page as expected.

Out-of-Proc Worker: Swagger UI

Migration from .NET Core 3.1 to .NET 6

If you want to migrate your existing .NET Core 3.1 function app to .NET 6, all you need to do is to update the .csproj file and update the package version and target framework. Open your .csproj file (LegacyInProcApp.csproj in this example), and update TargetFramework node from netcoreapp3.1 to net6.0 and AzureFunctionsVersion from v3 to v4 (line #4-5, 8-9).

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <!-- Change these values -->
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <AzureFunctionsVersion>v3</AzureFunctionsVersion>

    <!-- To these values -->
    <TargetFramework>net6.0</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>

    ...
  </PropertyGroup>
  ...
</Project>

Then, update all the Azure Functions related NuGet packages to the latest version, including the OpenAPI extension.

In-Proc Worker: Migration

Rebuild the project, run the function app by clicking the "Debug" button at the top. Next, open a web browser and go to http://localhost:7071/api/swagger/ui, and you will see the Swagger UI page as expected.

In-Proc Worker: Swagger UI after Migration

Migration from .NET 5 to .NET 6

If you want to migrate your existing .NET 5 function app to .NET 6, all you need to do is to update the .csproj file and update the package version and target framework. Open your .csproj file (LegacyOutOfProcApp.csproj in this example), and update TargetFramework node from net5.0 to net6.0 and AzureFunctionsVersion from v3 to v4 (line #4-5, 8-9).

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <!-- Change these values -->
    <TargetFramework>net5.0</TargetFramework>
    <AzureFunctionsVersion>v3</AzureFunctionsVersion>

    <!-- To these values -->
    <TargetFramework>net6.0</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>

    ...
  </PropertyGroup>
  ...
</Project>

Then, update all the Azure Functions related to NuGet packages to the latest version, including the OpenAPI extension.

Out-of-Proc Worker: Migration

Out-of-Proc Worker: Swagger UI after Migration

Now, you are able to build a new function app in .NET 6, as well as migrate your existing function apps to .NET 6 with minimal effort.

Try It Today

If you want to know more about using this extension, visit this page. If you want to try even more about its advanced features, see this documentation page.

And don't miss out our session at .NET Conf – Brand New! Azure Functions OpenAPI Extension on .NET 6 – live streaming on Nov 10, 9.30pm Pacific Time (Nov 11, 5.30am UTC) and on-demand available after the conference!

We're listening to your feedback while you are using this extension! So if you find something to suggest, improve or have any questions, please let us know.

Updated Nov 08, 2021

Version 1.0

azure functions