AzureExtensions.Swashbuckle 5.0.5

AzureExtensions.Swashbuckle

Swagger and Swagger UI for Azure Functions (isolated worker model) powered by Swashbuckle. Supports OpenAPI 2.0, 3.0, and 3.1.

<p align="center">

</p>

<p align="center">

</p>

What's New in v5.0.5

• Fixed ConfigureFunctionsWebApplication compatibility — removed AddMvcCore() which registered the full MVC routing pipeline, conflicting with Azure Functions HTTP routing and causing requests to hang
• New Integration test CI workflow — validates all Swagger endpoints on both Linux and Windows via func start
• Cleaned up TestFunction SwaggerController (removed diagnostic logging)

What's New in v5.0.4

• New IActionResult-based extension methods for ConfigureFunctionsWebApplication
  • CreateSwaggerJsonDocumentResult, CreateSwaggerYamlDocumentResult, CreateSwaggerUIResult, CreateSwaggerOAuth2RedirectResult
  • Uses ContentResult — no HttpResponseData pipeline issues
• New SwaggerValidate self-test endpoint in TestFunction
• Fixed startup crash (0x80008096) caused by missing MVC core service registrations
• Added test fakes (FakeHttpRequestData, FakeHttpResponseData) for extension method testing
• Added 55 new tests: 25 HttpResponseData extension + 16 IActionResult extension + 14 DI functional (191 total)

What's New in v5.0.1

• Updated embedded Swagger UI from v5.11 to v5.32.0
• Fixed resource leaks in response extension methods
• Fixed route parameter regex matching bug
• Fixed FunctionContext incorrectly treated as body parameter (#122)
• Fixed XML documentation file not found in TFM subdirectories (#114)
• Fixed Content-Type header on JSON/YAML responses (#119)
• Added IDisposable to SwashbuckleConfig for proper cleanup
• Added 136 unit, integration, and end-to-end tests

Features

• Isolated Worker Model — Built for Azure Functions v4 isolated worker (the recommended model going forward)
• Swashbuckle 10.x — Latest Swashbuckle.AspNetCore with Microsoft.OpenApi v2 support
• OpenAPI 2.0 / 3.0 / 3.1 — Generate specs in any supported version
• Swagger UI — Embedded Swagger UI served directly from your Azure Function
• Multi-document — Define multiple API versions/documents
• XML Comments — Automatic parameter and response documentation from XML docs
• Custom Attributes — [QueryStringParameter], [RequestHttpHeader], [SwaggerUploadFile], [RequestBodyType]
• OAuth2 Support — Built-in OAuth2 redirect endpoint and client configuration
• Newtonsoft.Json — Optional Newtonsoft serialization support
• Multi-targeting — .NET 8.0 (LTS) and .NET 9.0 (STS)

Installation

dotnet add package AzureExtensions.Swashbuckle

Quick Start

1. Register the Extension in Program.cs

using AzureFunctions.Extensions.Swashbuckle;
using AzureFunctions.Extensions.Swashbuckle.Settings;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.OpenApi;

var host = new HostBuilder()
    .ConfigureFunctionsWebApplication()
    .ConfigureServices((hostContext, services) =>
    {
        services.AddSwashBuckle(opts =>
        {
            opts.RoutePrefix = "api";
            opts.SpecVersion = OpenApiSpecVersion.OpenApi3_0;
            opts.AddCodeParameter = true;
            opts.PrependOperationWithRoutePrefix = true;
            opts.XmlPath = "MyFunctionApp.xml";
            opts.Documents = new[]
            {
                new SwaggerDocument
                {
                    Name = "v1",
                    Title = "My API",
                    Description = "My Azure Functions API",
                    Version = "v1"
                }
            };
            opts.Title = "My API";
        });
    })
    .Build();

host.Run();

Note: AddSwashBuckle is fully compatible with ConfigureFunctionsWebApplication (ASP.NET Core integration). It does not register AddMvcCore() — only the minimal services needed for API description, so it won't interfere with Azure Functions HTTP routing.

2. Add Swagger Endpoints

Recommended — use IActionResult with ConfigureFunctionsWebApplication:

public class SwaggerController
{
    private readonly ISwashBuckleClient swashBuckleClient;

    public SwaggerController(ISwashBuckleClient swashBuckleClient)
    {
        this.swashBuckleClient = swashBuckleClient;
    }

    [SwaggerIgnore]
    [Function("SwaggerJson")]
    public async Task<IActionResult> SwaggerJson(
        [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "Swagger/json")]
        HttpRequest req)
    {
        return await this.swashBuckleClient.CreateSwaggerJsonDocumentResult(req);
    }

    [SwaggerIgnore]
    [Function("SwaggerYaml")]
    public async Task<IActionResult> SwaggerYaml(
        [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "Swagger/yaml")]
        HttpRequest req)
    {
        return await this.swashBuckleClient.CreateSwaggerYamlDocumentResult(req);
    }

    [SwaggerIgnore]
    [Function("SwaggerUi")]
    public async Task<IActionResult> SwaggerUi(
        [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "Swagger/ui")]
        HttpRequest req)
    {
        return await this.swashBuckleClient.CreateSwaggerUIResult(req, "swagger/json");
    }
}

3. Open Swagger UI

Navigate to https://your-function-app/api/swagger/ui in your browser.

Configuration Options

XML Documentation

Enable XML doc generation in your .csproj:

<PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Then pass the XML path:

opts.XmlPath = "MyFunctionApp.xml";

Multiple Documents

opts.Documents = new[]
{
    new SwaggerDocument { Name = "v1", Title = "API v1", Version = "v1" },
    new SwaggerDocument { Name = "v2", Title = "API v2", Version = "v2" }
};

OAuth2

opts.ConfigureSwaggerGen = x =>
{
    x.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme
    {
        Type = SecuritySchemeType.OAuth2,
        Flows = new OpenApiOAuthFlows
        {
            Implicit = new OpenApiOAuthFlow
            {
                AuthorizationUrl = new Uri("https://your.idserver.net/connect/authorize"),
                Scopes = new Dictionary<string, string>
                {
                    { "api.read", "Access read operations" },
                    { "api.write", "Access write operations" }
                }
            }
        }
    });
};

opts.ClientId = "your.client.id";
opts.OAuth2RedirectPath = "http://localhost:7071/api/swagger/oauth2-redirect";

Custom Attributes

// Add query string parameters
[QueryStringParameter("page", "Page number", DataType = typeof(int), Required = false)]
[Function("GetItems")]
public async Task<HttpResponseData> GetItems(...)

// Add required HTTP headers
[RequestHttpHeader("X-Api-Key", isRequired: true)]
[Function("SecureEndpoint")]
public async Task<HttpResponseData> SecureEndpoint(...)

// File upload
[SwaggerUploadFile("file", "File to upload")]
[Function("Upload")]
public async Task<HttpResponseData> Upload(...)

Newtonsoft.Json Support

services.AddSwashBuckle(opts =>
{
    opts.AddNewtonsoftSupport = true;
    // ...
});

Migration from v4.x to v5.x

v5.0 includes breaking changes due to the Swashbuckle 10.x / Microsoft.OpenApi v2 upgrade:

Async Document Methods

// v4.x
Stream json = client.GetSwaggerJsonDocument(req, "v1");

// v5.x
Stream json = await client.GetSwaggerJsonDocumentAsync(req, "v1");

Sample Project

See the TestFunction project for a complete working example.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

Copyright © 2026, Vitali Bibikov. Code released under the MIT License.