openapi-out-of-proc.md

Microsoft.Azure.Functions.Worker.Extensions.OpenApi

This enables Azure Functions to render OpenAPI document and Swagger UI. Unlike the other extension, Microsoft.Azure.WebJobs.Extensions.OpenApi, this supports out-of-process model running on .NET 5 and later.

NOTE: This extension supports both OpenAPI 2.0 (aka Swagger) and OpenAPI 3.0.1 spec.

Acknowledgement

• Swagger UI version used for this library is v3.44.0 under the Apache 2.0 license.

Issues?

While using this library, if you find any issue, please raise a ticket on the Issue page.

Getting Started

For detailed getting started document, find this Enable OpenAPI Endpoints on Azure Functions – Out-of-Process Model page.

Advanced Configuration in General

If you look for the advanced configurations in general, please find the document, Advanced Configurations for OpenAPI Extension

Injecting OpenApiConfigurationOptions during Startup

You may want to inject the OpenApiConfigurationOptions instance during startup, through the Program.cs class. Here's the example:

namespace MyFunctionApp
{
    public class Program
    {
        public static void Main()
        {
            var host = new HostBuilder()
                .ConfigureFunctionsWorkerDefaults(worker => worker.UseNewtonsoftJson())
                /* ⬇️⬇️⬇️ Add this ⬇️⬇️⬇️ */
                .ConfigureServices(services =>
                {
                    services.AddSingleton<IOpenApiConfigurationOptions>(_ =>
                            {
                                var options = new OpenApiConfigurationOptions()
                                {
                                    Info = new OpenApiInfo()
                                    {
                                        Version = "1.0.0",
                                        Title = "Swagger Petstore",
                                        Description = "This is a sample server Petstore API designed by [http://swagger.io](http://swagger.io).",
                                        TermsOfService = new Uri("https://github.com/Azure/azure-functions-openapi-extension"),
                                        Contact = new OpenApiContact()
                                        {
                                            Name = "Enquiry",
                                            Email = "azfunc-openapi@microsoft.com",
                                            Url = new Uri("https://github.com/Azure/azure-functions-openapi-extension/issues"),
                                        },
                                        License = new OpenApiLicense()
                                        {
                                            Name = "MIT",
                                            Url = new Uri("http://opensource.org/licenses/MIT"),
                                        }
                                    },
                                    Servers = DefaultOpenApiConfigurationOptions.GetHostNames(),
                                    OpenApiVersion = OpenApiVersionType.V2,
                                    IncludeRequestingHostName = true,
                                    ForceHttps = false,
                                    ForceHttp = false,
                                };

                                return options;
                            });
                })
                /* ⬆️⬆️⬆️ Add this ⬆️⬆️⬆️ */
                .Build();

            host.Run();
        }
    }
}

Injecting OpenApiCustomUIOptions during Startup

You may want to inject the OpenApiCustomUIOptions instance during startup, through the Program.cs class. Here's the example:

namespace MyFunctionApp
{
    public class Program
    {
        public static void Main()
        {
            var host = new HostBuilder()
                .ConfigureFunctionsWorkerDefaults(worker => worker.UseNewtonsoftJson())
                /* ⬇️⬇️⬇️ Add this ⬇️⬇️⬇️ */
                .ConfigureServices(services =>
                {
                    services.AddSingleton<IOpenApiCustomUIOptions>(_ =>
                            {
                                var assembly = Assembly.GetExecutingAssembly();
                                var options = new OpenApiCustomUIOptions(assembly)
                                {
                                    CustomStylesheetPath = "https://contoso.com/dist/my-custom.css",
                                    CustomJavaScriptPath = "https://contoso.com/dist/my-custom.js",

                                    // ⬇️⬇️⬇️ Add your logic to get your custom stylesheet ⬇️⬇️⬇️
                                    // GetStylesheet = () =>
                                    // {
                                    //     var result = string.Empty;

                                    //     //
                                    //     // CUSTOM LOGIC TO GET STYLESHEET
                                    //     //

                                    //     return Task.FromResult(result);
                                    // },
                                    // ⬆️⬆️⬆️ Add your logic to get your custom stylesheet ⬆️⬆️⬆️

                                    // ⬇️⬇️⬇️ Add your logic to get your custom JavaScript ⬇️⬇️⬇️
                                    // GetJavaScript = () =>
                                    // {
                                    //     var result = string.Empty;

                                    //     //
                                    //     // CUSTOM LOGIC TO GET JAVASCRIPT
                                    //     //

                                    //     return Task.FromResult(result);
                                    // },
                                    // ⬆️⬆️⬆️ Add your logic to get your custom JavaScript ⬆️⬆️⬆️
                                };

                                return options;
                            });
                })
                /* ⬆️⬆️⬆️ Add this ⬆️⬆️⬆️ */
                .Build();

            host.Run();
        }
    }
}

Injecting OpenApiHttpTriggerAuthorization during Startup

You may want to inject the OpenApiHttpTriggerAuthorization instance during startup, through the Program.cs class. Here's the example:

namespace MyFunctionApp
{
    public class Program
    {
        public static void Main()
        {
            var host = new HostBuilder()
                .ConfigureFunctionsWorkerDefaults(worker => worker.UseNewtonsoftJson())
                /* ⬇️⬇️⬇️ Add this ⬇️⬇️⬇️ */
                .ConfigureServices(services =>
                {
                    services.AddSingleton<IOpenApiHttpTriggerAuthorization>(_ =>
                            {
                                var auth = new OpenApiHttpTriggerAuthorization(req =>
                                {
                                    var result = default(OpenApiAuthorizationResult);

                                    var authtoken = (string)req.Headers["Authorization"];
                                    if (authtoken.IsNullOrWhiteSpace())
                                    {
                                        result = new OpenApiAuthorizationResult()
                                        {
                                            StatusCode = HttpStatusCode.Unauthorized,
                                            ContentType = "text/plain",
                                            Payload = "Unauthorized",
                                        };

                                        return Task.FromResult(result);
                                    }

                                    return Task.FromResult(result);
                                });

                                return auth;
                            });
                })
                /* ⬆️⬆️⬆️ Add this ⬆️⬆️⬆️ */
                .Build();

            host.Run();
        }
    }
}