Swashbuckle.AspNetCore.CleanRequests
A library with additional filters for Swashbuckle.AspNetCore to exclude duplicated information from schema.
Introduction
Well designed RESTful APIs often use nesting on endpoints to show relationships between entities, so it's easier to understand them. In addition many modern web applications use Mediator pattern to achieve loose coupling between objects (see MediatR library for example implementation). An example RESTful request is shown below.
[HttpPut("{orderId:int}/items/{itemId:int}")]
public ActionResult<int> UpdateOrderItem(int orderId, int itemId,
[FromBody] UpdateOrderItemRequest request)
{
request.OrderId = orderId;
request.ItemId = itemId;
// ...
}
The problem is that both the URL and the UpdateOrderItemRequest
class contain orderId
and itemId
, while only the URL values are used. Unfortunately Swagger doesn't know that, so you have to deal with it manually. You can create an additional class without duplicated properties, put it into the endpoint definition and map it to the UpdateOrderItemRequest
, or you can use this library to exclude duplicates.
Important
The library is designed with the assumption that request classes are used only once per request.
It means that you should not use UpdateOrderItemRequest
for different requests.
Installation
Install Nuget package into your ASP.NET Core application.
Package Manager
Install-Package Swashbuckle.AspNetCore.CleanRequests -Version {version}
.NET CLI
dotnet add package --version {version} Swashbuckle.AspNetCore.CleanRequests
Usage
-
In the
ConfigureServices
method ofStartup.cs
search forAddSwaggerGen
call and register the filters. Define where to look for duplicates usingParameterLocation
enum (the default value isParameterLocation.Path
).builder.Services.AddSwaggerGen(options => { options.ExcludeDuplicatedBodyProperties(ParameterLocation.Path); options.ExcludeDuplicatedQueryParameters(ParameterLocation.Path); });
-
Now you can start your application and check out the schemas.
Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.