NSwag / Redoc Integration

The Toggly.FeatureManagement.NSwag package automatically excludes API endpoints from Swagger/OpenAPI documentation when their associated feature flags are disabled. This keeps your API documentation in sync with your feature flag state, ensuring developers only see endpoints that are actually available.

Benefits

• Accurate Documentation: Swagger documentation automatically reflects the current state of your feature flags, preventing confusion from seeing disabled endpoints
• Dynamic Updates: The Swagger document is cached but auto-invalidated when feature definitions change, so toggles reflect without app restarts
• Reduced Maintenance: No need to manually update documentation when feature flags change
• Better Developer Experience: API consumers only see endpoints they can actually use

Installation

Install-Package Toggly.FeatureManagement.NSwag

Setup

In your Startup.cs or Program.cs, add the feature gate filtering to your NSwag configuration:

using Toggly.FeatureManagement.NSwag.Configuration;

services.AddOpenApiDocument((config, services) =>
{
    config.Title = "My API";
    config.DocumentName = "v1";
    
    // Add feature gate filtering
    config.AddFeatureGateFiltering(services);
    
    // ... rest of your NSwag configuration
});

// Serve the filtered document (bypasses NSwag internal cache)
// Important: use UseFeatureAwareOpenApi instead of UseOpenApi
app.UseFeatureAwareOpenApi();
app.UseSwaggerUi();

Example Usage

Controllers or actions annotated with [FeatureGate] attributes are automatically filtered from Swagger when their feature flags are disabled:

using Microsoft.FeatureManagement.Mvc;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]
[FeatureGate(FeatureFlags.ExperimentalFeature)]
public class ExperimentalController : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        return Ok("This endpoint is only visible in Swagger when ExperimentalFeature is enabled");
    }
}

How It Works

1. The FeatureGateOperationProcessor examines each API endpoint during Swagger document generation
2. It checks for [FeatureGate] attributes on both the controller class and action methods
3. If a [FeatureGate] attribute is found, it evaluates the associated feature flags using IFeatureManager
4. If the feature flags are disabled (based on RequirementType), the endpoint is excluded from the Swagger document
5. The document is cached for performance, and the cache is cleared when feature definitions change; the next request regenerates it with current flags

ReDoc Integration

The feature flag filtering automatically extends to ReDoc and any other tool that consumes the OpenAPI/Swagger JSON document. Since ReDoc renders documentation based on the OpenAPI specification generated by NSwag, endpoints filtered from the Swagger document will also be automatically excluded from the ReDoc UI.

This means you get the same benefits when using ReDoc to render a clean, modern UI for your API documentation:

• Consistent Filtering: Endpoints with disabled feature flags are hidden in both Swagger UI and ReDoc
• No Additional Configuration: The filtering works automatically with ReDoc - no extra setup required
• Dynamic Updates: As feature flags change, both Swagger and ReDoc documentation update automatically

Simply configure ReDoc to point to your filtered Swagger document (e.g., /swagger/v1/swagger.json), and the feature flag filtering will be applied automatically.

Supported Features

• Controller & Action Support: Works with both controller-level and action-level [FeatureGate] attributes
• Requirement Types: Supports both RequirementType.All (all features must be enabled) and RequirementType.Any (at least one feature must be enabled)
• Automatic Filtering: Endpoints with [FeatureGate] attributes are automatically excluded when their feature flags are disabled
• Default Behavior: Endpoints without [FeatureGate] attributes are always included in Swagger

info

The Swagger document is cached and automatically invalidated when feature definitions change (HTTP refresh, snapshot load, or live update). The next request regenerates it, so you can turn features on/off without restarting the application and the documentation stays current.

Requirements

• .NET Standard 2.1 or later
• NSwag.AspNetCore 14.6.3 or compatible
• Microsoft.FeatureManagement.AspNetCore 4.3.0 or compatible
• Toggly.FeatureManagement (base package)

Notes

• Endpoints without [FeatureGate] attributes are always included in Swagger
• If IFeatureManager is not available in the service provider, endpoints are included by default
• The processor supports both RequirementType.All (all features must be enabled) and RequirementType.Any (at least one feature must be enabled)

Working example

Explore the .NET SDK Sample. Its guided sections include the first flag, request identity, Order VIP targeting, filter presets, named variants, Hangfire, health checks, and OpenAPI filtering. The README maps each section to its source files and includes a manual walkthrough.