A collection of Swashbuckle.AspNetCore filters to add examples, security headers, and authorization indicators to Swagger documentation.
Swashbuckle.AspNetCore.Filters is a NuGet library that provides a collection of filters for Swashbuckle.AspNetCore to enhance Swagger/OpenAPI documentation. It solves the problem of generic or incomplete API docs by adding realistic request/response examples, security requirements for authenticated endpoints, custom headers, and authorization indicators, making APIs easier to test and integrate.
ASP.NET Core developers using Swashbuckle.AspNetCore for API documentation who need to improve Swagger UI with custom examples, security details, or header management for client consumption.
Developers choose this library because it offers a straightforward way to add practical, real-world enhancements to Swagger documentation without modifying core Swashbuckle logic, with features like automatic example generation and OAuth2 support that streamline API testing and documentation.
A bunch of useful filters for Swashbuckle.AspNetCore
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.
Automatically populates Swagger with realistic request and response examples using IExamplesProvider<T>, making API testing and demos more effective with custom data, as shown in the README's screenshot comparisons.
Adds OAuth2 bearer token support to Swagger UI for endpoints with [Authorize] attributes via SecurityRequirementsOperationFilter, enabling easy authentication during testing without manual configuration.
Allows injection of custom request and response headers, such as correlation IDs, through simple operation filters like AddHeaderOperationFilter and SwaggerResponseHeader attributes.
Provides IMultipleExamplesProvider<T> for showcasing different use cases per endpoint with named examples and summaries, enhancing documentation clarity for complex APIs.
Supports constructor injection in example providers, enabling dynamic example generation from services like IHostingEnvironment, as demonstrated in the 'Advanced' section.
The README openly discourages using request/response example filters, noting that Swashbuckle's built-in XML comment support (available since 2018) is preferred for most cases, making some library features feel obsolete.
Requires meticulous configuration in Startup.cs with multiple filter registrations and service calls, and the version compatibility table shows tight coupling to Swashbuckle.AspNetCore versions, risking breakage during upgrades.
Admits known issues like no support for request examples on querystring parameters, and multiple examples are incompatible with OpenAPI 2.0 serialization, forcing trade-offs in documentation output.
While automatic annotation is supported, complex scenarios still require manual SwaggerRequestExample/SwaggerResponseExample attributes, adding boilerplate code that contradicts the 'grab-bag' simplicity promise.