This article is contributed. See the original author and article here.

Since the last update of v1.4.0, this Azure Functions OpenAPI extension has a lot of improvements. Here in this post, let’s discuss what improvements have been made.


Update – v1.5.0


.NET 7 support for the isolated worker extension


According to the Azure Functions roadmap, Azure Functions isolated worker model has started supporting .NET 7. Therefore, this OpenAPI extension also starts supporting .NET 7 with the isolated worker model. The migration step is as easy as changing the target framework. Update your .csproj file and find the node, and change it from netcoreapp3.1 (.NET Core 3.1), net5.0 (.NET 5) or net6.0 (.NET 6), to net7.0 (.NET 7).


 



  
    net7.0
    v4
    Exe
    ...
  
  ...
  
    ...
    
  
  ...

 


OpenAPI settings instance support out-of-the-box


There are many environment variables related to the OpenAPI extension. All of them are prefixed with OpenApi__ as the environment variables. These environment variables can now be read through the OpenApiSettings instance, injected directly from the extension package. So, all you need to do is to inject the instance.


Here’s the sample code for the in-proc worker model:


 

// in-proc worker function
public class Function1
{
    private readonly OpenApiSettings _openapi;
    private readonly ILogger _logger;

    // Inject OpenApiSettings instance through the constructor.
    public Function1(OpenApiSettings openapi, ILogger logger)
    {
        _openapi = openapi;
        _logger = logger;
    }
    ...
}

 


And here’s the sample code for the isolated worker model:


 

// out-of-proc worker function
public class Function1
{
    private readonly OpenApiSettings _openapi;
    private readonly ILogger _logger;

    // Inject OpenApiSettings instance through the constructor.
    public Function1(OpenApiSettings openapi, ILoggerFactory loggerFactory)
    {
        _openapi = openapi;
        _logger = loggerFactory.CreateLogger();
    }
    ...
}

 


GitHub Actions workflow support


You can now generate the OpenAPI document on-the-fly within the GitHub Actions workflow. You can find more details on this document. Here’s the sample usage:


 

steps:
- name: Checkout the repository
  uses: actions/checkout@v2

- name: Setup .NET SDK 7 LTS
  uses: actions/setup-dotnet@v1
  with:
    dotnet-version: '7.x'

- name: Restore NuGet packages
  shell: pwsh
  run: |
    dotnet restore .

- name: Build solution
  shell: pwsh
  run: |
    dotnet build . -c Debug -v minimal

- name: Generate OpenAPI document
  id: oai
  uses: Azure/azure-functions-openapi-extension/actions/build-openapi@v1
  with:
    functionAppPath: 'bin/Debug/net7.0'
    requestUri: 'http://localhost:7071/api/openapi/v3.json'
    documentPath: 'generated'
    documentName: 'openapi.json'
    delay: '30'
    isRemote: 'false'

- name: Check generated OpenAPI document
    shell: pwsh
    run: |
      echo "Generated Document: ${{ steps.oai.outputs.generated }}"

      $json = Get-Content -Path ${{ steps.oai.outputs.generated }} | ConvertFrom-Json
      $result = $json.openapi -eq "3.0.1"
      echo "Check result: $result"

 


Generic CI/CD pipeline support


In addition to supporting GitHub Actions workflow, both PowerShell script and bash shell script are provided to support generic CI/CD pipelines, including Azure DevOps.


Here’s the PowerShell script:


 

& $([Scriptblock]::Create($(Invoke-RestMethod https://aka.ms/azfunc-openapi/generate-openapi.ps1))) `
    -FunctionAppPath     `
    -BaseUri             `
    -Endpoint            `
    -OutputPath          `
    -OutputFilename      `
    -Delay               `
    -UseWindows         

 


And here’s the bash shell script:


 

curl -fsSL https://aka.ms/azfunc-openapi/generate-openapi.sh 
    | bash -s -- 
        -p|--functionapp-path    
        -u|--base-uri            
        -e|--endpoint            
        -o|--output-path         
        -f|--output-filename     
        -d|--delay              

 


Update – v2.0.0-preview1


Breaking changes



  • The OpenApiHttpTriggerAuthorization class has now become a property of the OpenApiConfigurationOptions class.

  • The property, IncludeRequestingHost of OpenApiConfigurationOptions has now become ExcludeRequestingHost, and its default value is false.


Azure Functions Easy Auth support


If your Azure Function app implements the Easy Auth feature for better AuthN scenarios, the authN’d claims can be directly used for Swagger UI and OpenAPI document generation through the OpenApiHttpTriggerAuthorization class.


Here’s the sample code for the in-proc worker model:


 

// in-proc worker function
public class Startup : FunctionsStartup
{
    public override void Configure(IFunctionsHostBuilder builder)
    {
        builder.Services.AddSingleton(_ =>
                        {
                            var options = new OpenApiConfigurationOptions()
                            {
                                ...
                                Security = new OpenApiHttpTriggerAuthorization(async req =>
                                {
                                    var result = default(OpenApiAuthorizationResult);

                                    // Add your custom authorisation logic like below
                                    var identities = req.Identities;

                                    return await Task.FromResult(result).ConfigureAwait(false);
                                }),
                            };

                            return options;
                        });
    }
}

 


And here’s the sample code for the isolated worker model:


 

public class Program
{
    public static void Main()
    {
        var host = new HostBuilder()
            .ConfigureServices(services =>
            {
                services.AddSingleton(_ =>
                        {
                            var options = new OpenApiConfigurationOptions()
                            {
                                ...
                                Security = new OpenApiHttpTriggerAuthorization(async req =>
                                {
                                    var result = default(OpenApiAuthorizationResult);

                                    // Add your custom authorisation logic like below
                                    var identities = req.Identities;

                                    return await Task.FromResult(result).ConfigureAwait(false);
                                }),
                            };

                            return options;
                        });
            })
            .Build();

        host.Run();
    }
}

 


Tell us what you think


There are a bunch of improvements released in this new version. Also, We’ve started gradually upgrading the extension version to v2.0.0. So if you have any questions, issues, suggestions or something else, please let us know!

Brought to you by Dr. Ware, Microsoft Office 365 Silver Partner, Charleston SC.