SwaggerEnrichers
is a C# package that offers a more flexible and convenient way to add ISchemaFilter
and IParameterFilter
using attributes. While you can use the SwaggerSchemaAttribute
from Swashbuckle.AspNetCore.Annotations
, SwaggerEnrichers
allows you to configure example values, value type and so on.
SwaggerEnrichers
comprises an ISchemaFilter
and an IParameterFilter
that analyze incoming classes, parameters, and properties. The filters look for attributes that implement IParameterEnricher
or ISchemaEnricher
, once they find these attributes, they use their Enrich methods to modify the schema or parameter.
SwaggerEnrichers is available on NuGet and can be installed via the below commands:
$ Install-Package SwaggerEnrichers
or via the .NET Core CLI:
$ dotnet add package SwaggerEnrichers
To get started with SwaggerEnrichers
, you need to add the necessary filters to SwaggerGen
:
builder.Services.AddSwaggerGen(options =>
{
options.AddEnricherFilters();
});
After that, you need to create an attribute that implements ISchemaFilter
or IParameterFilter
. You can create an attribute that implements both as well:
public class ProductViewIdAttribute : Attribute, ISchemaEnricher, IParameterEnricher
{
public void Enrich(OpenApiSchema schema)
{
schema.Title = "Product Id";
schema.Description = "Product identifier";
schema.Example = new OpenApiInteger(3);
}
public void Enrich(OpenApiParameter parameter)
{
parameter.Name = "Product Id";
parameter.Description = "Product identifier";
parameter.Schema.Example = null;
}
}
public class ProductViewNameAttribute : Attribute, ISchemaEnricher, IParameterEnricher
{
public void Enrich(OpenApiSchema schema)
{
schema.Title = "Product Name";
schema.Description = "Name of product";
schema.Example = new OpenApiString("Apple Watch");
}
public void Enrich(OpenApiParameter parameter)
{
parameter.Name = "Product Name";
parameter.Description = "Name of product";
parameter.Schema.Example = null;
}
}
Now, you can apply these attributes to any class
, parameter
, property
, or member
:
public class ProductView
{
[ProductViewId]
public required int Id { get; init; }
[ProductViewName]
public required string Name { get; init; }
[ProductViewPrice]
public required decimal Price { get; init; }
[ProductViewType]
public required string Type { get; init; }
}
[Route("api/product")]
[ApiController]
public class ProductController : ControllerBase
{
[HttpGet]
[Route("id/{id}")]
public ActionResult<ProductView> GetProductById([ProductViewId] string id)
{
return Ok();
}
[HttpGet]
[Route("name/{name}")]
public ActionResult<ProductView> GetProductByName([ProductViewName] string name)
{
return Ok();
}
[HttpGet]
public ActionResult<List<ProductView>> GetProducts([FromQuery] GetProductsQueryView getProductsQueryView)
{
return Ok();
}
[HttpPost]
public ActionResult PostProduct(ProductView productView)
{
return NoContent();
}
}
For more complex examples see Demo
project