Swashbuckle.AspNetCore.Filters Documentation

The AppendAuthorizeToSummaryOperationFilter adds an indicator (e.g., (Auth)) to the action's summary in Swagger UI if the endpoint has an [Authorize] attribute. This helps developers quickly identify which endpoints require authentication.

Note: You must call c.IncludeXmlComments(...) before adding this filter.

Swagger examples are rendered using the same JSON serializer configuration used by your controllers in services.AddControllers().

For Minimal APIs (.NET 5+), the library defaults to System.Text.Json.JsonSerializerDefaults.Web, which results in camelCase output. Note that PascalCase is not supported for Minimal APIs.

Since May 2018, Swashbuckle.AspNetCore supports adding examples directly via XML comments. This is the recommended approach and should be used instead of ExamplesOperationFilter whenever possible. XML comments work for request/response bodies and even for querystring or route parameters (e.g., on GET requests).

Use the <example> tag within a <summary> or on a property to define the example value.

public class Product
{
    /// <summary>
    /// The name of the product
    /// </summary>
    /// <example>Men's basketball shoes</example>
    public string Name { get; set; }
}

The SecurityRequirementsOperationFilter adds security information to each operation, enabling the 'Authorize' button in Swagger UI. This allows users to send an Authorization header (e.g., a Bearer token) to protected endpoints.

To use this, you must also define the security scheme using c.AddSecurityDefinition.

The Request and Response example filters allow you to populate paths.path.[http-verb].requestBody.content.[content-type].example and the response example in Swagger UI with custom, realistic data instead of autogenerated placeholders.

As of version 5.0.0-beta, XML examples are also supported.

Use these filters to inject headers into the Swagger documentation:

• Add a request header: Use AddHeaderOperationFilter to add a specific string to all requests (e.g., a correlationId).
• Add a response header: Use AddResponseHeadersFilter to specify response headers for operations.

Install the Swashbuckle.AspNetCore.Filters NuGet package. Ensure you select the version compatible with your Swashbuckle.AspNetCore version:

dotnet add package Swashbuckle.AspNetCore.Filters

To add examples to API responses, implement IExamplesProvider<T> where T is the return type.

Automatic Annotation: Works if the action return type is clearly defined (e.g., ActionResult<T> or T).

Manual Annotation: Use the [SwaggerResponseExample(statusCode, typeof(ExampleClass))] attribute to explicitly link a provider to a specific HTTP status code. This overrides automatic detection.

// Implementation
public class CountryExamples : IExamplesProvider<List<Country>>
{
    public List<Country> GetExamples()
    {
        return new List<Country> { new Country { Code = "AA", Name = "Test" } };
    }
}

// Usage
[SwaggerResponse(200, "The list of countries", typeof(IEnumerable<Country>))]
[SwaggerResponseExample(200, typeof(CountryExamples))]
public async Task<HttpResponseMessage> Get(string lang)

If your examples need to access services (e.g., reading data from a database or checking the environment), you can use constructor injection in your IExamplesProvider implementation.

1. Implement IExamplesProvider with the required dependencies in the constructor.
2. Register the examples using the appropriate extension method.

internal class PersonRequestExample : IExamplesProvider
{
    private readonly IHostingEnvironment _env;

    public PersonRequestExample(IHostingEnvironment env)
    {
        _env = env;
    }

    public object GetExamples()
    {
        return new PersonRequest 
        { 
            Age = 24, 
            FirstName = _env.IsDevelopment() ? "Development" : "Production", 
            Income = null 
        };
    }
}

To ensure that authorization requirements (like policies or roles) are visible in the Swagger documentation summary, use the [Authorize] attribute on your Controller or Action. The filter will extract the policy or role names and include them in the generated summary.

[Authorize]
public class ValuesController : Controller
{
    [Authorize("Customer")]
    public PersonResponse GetPerson([FromBody]PersonRequest personRequest)
    {
        // ...
    }
}