The developer’s toolkit: Swagger

Originally Published On AppFog

August 4, 2013

Share +

I know what you’re probably thinking: I’ve written this post to recommend developers to add swagger (note the small “s”) to their existing set of skills and attributes. While I certainly do not disrecommend swagger as a character trait, my purpose today is instead to talk about the Swagger (note the big “S”) API documentation and exploration tool.

Swagger enables you to transform your API into a sleek UI that makes it vastly easier for third-party users to see an exhaustive list of what your API offers, how requests are matched with URLs, and what the server will return in response to specific requests.

Swagger also provides a sandbox UI for experimentation with APIs. Have a look at the demo UI. What you find there is an API for a hypothetical pet store. If you click on “/pet” for example, this will open up a menu of all of the HTTP requests associated with that directory.

If I want to see what pets are available with the ID “Fido,” I simply need to open up the menu bar associated with GET /pet.json/{petId} requests, insert “Fido” into the text field, and hit the “Try it out!” button to get the API’s response:

What I get in response is the request URL, the response body (in this case the JSON document returned by the server), the response code (200, 404, etc.), and the response headers.

This is a very basic example, and the demo page doesn’t communicate with an actual server. But I hope that it puts at least a little bit of Swagger’s power on display. Fortunately, Swagger can also easily handle APIs that involve more advanced features like auth tokens, permalinks, posting information as an array, and so on.

There are other tools like Swagger, but Swagger is the most comprehensive that I’ve seen. The goal of Swagger is to “enable client and documentation systems to update at the same pace as the server.” Swagger is able to easily keep pace with changes that you introduce into your API/server because you can actually code for them.

There are currently a variety of clients in a variety of languages/frameworks that enable you to do so easily. For example, if you create a Node.js API, there’s a Node/Express client that enables you access to methods like addPOST, addGET, and many others that can change your Swagger interface from within your application code. Beyond Node.js, there are a variety of other clients available, including Scala Play!, Java SpringMVC, Symfony2, and others.

Just so that you know, there are a few limitations to be aware of: as it stands, Swagger supports JSON-based APIs only, so if you plan on producing an XML-based API or a mixed JSON/XML-based API, then you might want to seek out a different tool. There is also the limitation that not all languages and frameworks are currently directly integratable with Swagger, so that might also serve as a limitation. But Swagger is language-agnostic, so lack of a Swagger client for your preferred language/framework may also serve as a spur to make one on your own and contribute to the broader project.

Tools like Swagger have become essential because public-facing APIs have quite simply become one of the foundational cornerstones of data interchange in just a few years’ time. But getting APIs right is hard. APIs need to be easy for developers to use. They need to provide an intuitive interface in line with best practices. They require solid documentation. Companies like Apigee, Mashery, and others are devoted to enabling developers and companies to get APIs right.

Don’t be caught sleeping with an API that is documented and represented poorly or not at all. With tools like Swagger, turning your API into a pleasant experience for end-user developers no longer involves reinventing the wheel unnecessarily. Give it a shot!