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.
Defining consumes and produdes in Operation Object
In Swagger, HTTP verb like GET, POST, PUT, PATCH or 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/json, text/json, application/xml, text/xml, and application/x-www-form-urlencoded. And those four content types are the default response ones – application/json, text/json, application/xml and 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:
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.
Implementing SwaggerConsumesAttribute Decorator
First of all, we need to write a simple decorator, called SwaggerConsumesAttribute which handles the consumes field of the Operation Object.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Through this decorator, we simply define number of content types to pass. How does it apply?
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
We now write the Consumes filter class by implementing the IOperationFilter interface like.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
To check the content type values passed from the SwaggerConsumerAttribute decorator, and
To add all content types passed from the decorator to operation.consumes.
This needs to be added to the Swashbuckle configuration like:
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Now run the Web API again and we’ll see the result like:
Implementing SwaggerProducesAttribute and Produces
Both SwaggerProducesAttribute decorator and Produces filter can be written as what we did above for consumes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The SwaggerProducesAttribute decorator can be applied to:
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.
Asp.Net Core has attributes [Produces(“application/json”)] and [Consumes(“application/json”)] that can be assigned to controller and SwahBuckle will understand them.
Paul Martin
Thanks, Just what I was looking for
martinpjr
@MichaelFreidgeim Thanks, just info I was looking for.
Great article was looking for this for a long time. The only thing that is missing is that you also need to add the Produces as an operation filer to the swagger config.
c.OperationFilter();
Comments are closed.
We use cookies to ensure that we give you the best experience on our website. If you continue to use this site we will assume that you are happy with it.YesNoPrivacy policy
Asp.Net Core has attributes [Produces(“application/json”)] and [Consumes(“application/json”)] that can be assigned to controller and SwahBuckle will understand them.
Thanks, Just what I was looking for
@MichaelFreidgeim Thanks, just info I was looking for.
Great article was looking for this for a long time. The only thing that is missing is that you also need to add the Produces as an operation filer to the swagger config.
c.OperationFilter();