Everybody loves Swagger

Swagger

Swagger is a specification which allows you to layout, describe and then document your API. It’s built around JSON to specify API metadata, structure and data models. This results in a language agnostic and machine readable interface which allows both humans and machines to smoothly understand the capabilities of your restful service. Since the version 2.0, the YAML format support has been introduced which makes it even more human readable.

Swagger has a growing developer community and cross-industry participation with a meaningful contribution which is leading to a wide adoption. Beside the specification Swagger has multiple implementations and a rich set of tools which enable you to generate interactive documentation (in sync with the application code), client/server code and potentially to build-up a toolset to help you to build a successful API program.

One of those tools is the built-in swagger-ui , a dependency-free collection of HTML, JavaScript, and CSS assets that takes the swagger API specification as input to visualize and consume your restful API. It’s basically shows the list of APIs (description, version, base path), you can than drill down and see the list of the operations with the http methods,  then the details of every operations, description parameters and return types finally can specify the parameters, try out the API and analyze the response.

ASP.NET

I first tried to add the Swagger documentation to my very basic Web.Api. At the moment Swashbuckle is the best option. Swashbuckle basically looks to the ApiExplorer and generate the swagger JSON self-documentation. It has an embedded version of the swagger-ui and it enables the automatic swagger spec generation simply adding the nuget package to your solution.

The automatically generated specifications are available at this address {baseaddress}/swagger/api-docs and the embedded ui at {baseaddress}/swagger.

The good news here is that Swagger will be integrated in the next version of ASP.NET / Visual Studio (not yet in the 2015 preview) as “confirmed” by Microsoft.
If you’re interested to try Swashbuckle, check-out this BlogPost with a detailed step by step guide.

Azure API Management

The Azure API Management allows you to create a new virtual API importing the Swagger or the WADL specification file and this is great. The procedure is straightforward and it’s described here http://azure.microsoft.com/en-us/documentation/articles/api-management-howto-import-api/

From the Swagger ui of the WebApi I created before, I got the JSON of the Characters controller clicking on the “raw” link and I imported it on API management. This is the result along with all the operations. 

After adding the API to a new product and after the publishing the virtual interface is accessible at this address https://coditapi.azure-api.net/bb/APIs/Characters?subscription-key={key}

Azure API Management already have a complete user interface to access to the API documentation and effective built-in console which helps developers to learn how to use the published APIs and speed-up testing. Unfortunately, at the moment the import procedure cannot be used to refresh (or create and swap) a previously created API. This means that the swagger spec cannot be used to keep in sync the virtual API with the backend API preserving the API management settings like security and policies.

Sentinet

Sentinet doesn’t support swagger out of the box so at the moment a possible solution is to introduce a custom implementation leveraging the Sentinet extensibility.

I reached out Andrew Slivker for a comment who confirmed that they’ve already planned to introduce the swagger after the 4.0 release.  I’m thrilled to see the Swagger integration with Sentinet so in the meanwhile I updated my Sentinet demo dashboard to embed the Swagger UI and to link to a swagger specification attached to a virtual REST API I created in Sentinet (or to a public API).

Conclusion

Swagger is governable, sharable and readable framework for describing, producing and consuming REST services. No matter which technology you use, no matter which language you prefer, it helps from the professional to the enterprise in the REST adoption that’s why everybody loves Swagger.

Cheers,

Massimo