There have been a few approaches to make sharing and consuming Web Services easier over the years. Many developers have worked with WSDL and SOAP services, as they were extremely popular in the early 2000’s and the beginnings of the .NET Framework. However, everything has moved on to being REST based and using JSON these days. This is a huge difference, and web service discoverability and sharing has needed to change in big ways as well. Swagger.io is a project that helps make RESTful APIs more easily sharable, discoverable, and self-documenting. Plus, Swagger is cross-platform and supports every popular programming language/framework.

Swagger is a powerful open source framework backed by a large ecosystem of tools that helps you design, build, document, and consume your RESTful APIs.

The way that Swagger works, is that you “swagger-enable” your API. In .NET you can do this by including a Nuget package called Swashbuckle. This will autogenerate a Swagger definition file (in JSON format) for your API that is easily accessible at a URL on your API’s site. Then you can use code generation tools to read this Swagger definition file and auto-generate client SDK code in any of the huge list of supported languages.

Swagger is really pretty amazing, and you can find the documentation with tutorials for the Swagger project at: http://swagger.io

Swagger not only auto-generates the definition file and client SDK’s but it also auto-generates a UI to be able to discover and test out your APIs as well. This is done using the Swagger UI. See the below screenshot for an example of what it looks like:

If you want to see what the Swagger UI looks like in more detail and try it out for yourself, here’s a live demo: http://petstore.swagger.io

About the Author