Open API 2.0 (AKA Swagger) is a de-facto standard to document Web API. For ASP.NET Web API applications, Swashbuckle helps developers build the Swagger definition a lot easier. As Swashbuckle hasn’t fully implemented the Swagger specification, we need to develop some extensions using a few interfaces provided by Swashbuckle. In this post we’re going to talk about a couple of extensions to make Swagger definition more completed.
The sample codes used in this post can be found here.
The sample application uses the following spec:
produdes in Operation Object
In Swagger, HTTP verb like
DELETE is referred as
Operation Object. Each Operation Object can define which content types are to be requested (
consumes) and which content types are to be returned (
produces). Therefore, with Swashbuckle, Swagger document page produces like:
In other words, Swashbuckle assumes those five content types as default for requests –
application/x-www-form-urlencoded. And those four content types are the default response ones –
text/xml. Here’s a part of the Swagger definition automatically generated.
If we want to globally apply those content types, that can be done within the global configuration. Here’s the sample OWIN configuration:
It clears everything and add only one content type –
application/json. By doing so, we can globally set one content type for both requests and responses. If we want to have more control on each endpoint, the
IOperationFilter interface of Swashbuckle gives us that flexibility.
First of all, we need to write a simple decorator, called
SwaggerConsumesAttribute which handles the
consumes field of the Operation Object.
Through this decorator, we simply define number of content types to pass. How does it apply?
Let’s move on.
We now write the
Consumes filter class by implementing the
IOperationFilter interface like.
What it does are:
- To check the content type values passed from the
- To add all content types passed from the decorator to
This needs to be added to the Swashbuckle configuration like:
Now run the Web API again and we’ll see the result like:
SwaggerProducesAttribute decorator and
Produces filter can be written as what we did above for
SwaggerProducesAttribute decorator can be applied to:
The picture below is the Swagger definition based on the extensions above:
We’ve so far had a look how to extend Swashbuckle to fill the missing parts in Swagger definition. In the next post, we’ll walk through another extension for Swagger definition.