SWASHBUCKLE PRO TIPS FOR ASP.NET WEB API – CONTENT TYPES

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.

Acknowledgement

The sample application uses the following spec:

Definingconsumesandprodudesin Operation Object

In Swagger, HTTP verb likeGET,POST,PUT,PATCHorDELETEis referred asOperation 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, andapplication/x-www-form-urlencoded. And those four content types are the default response ones –application/json,text/json,application/xmlandtext/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, theIOperationFilterinterface of Swashbuckle gives us that flexibility.

ImplementingSwaggerConsumesAttributeDecorator

First of all, we need to write a simple decorator, calledSwaggerConsumesAttributewhich handles theconsumesfield of the Operation Object.

Through this decorator, we simply define number of content types to pass. How does it apply?

Let’s move on.

ImplementingConsumesFilter

We now write theConsumesfilter class by implementing theIOperationFilterinterface like.

What it does are:

• To check the content type values passed from theSwaggerConsumerAttributedecorator, and
• To add all content types passed from the decorator tooperation.consumes.

This needs to be added to the Swashbuckle configuration like:

Now run the Web API again and we’ll see the result like:

ImplementingSwaggerProducesAttributeandProduces

BothSwaggerProducesAttributedecorator andProducesfilter can be written as what we did above forconsumes.

TheSwaggerProducesAttributedecorator 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.