Swagger is an emerging developer tool barely gracing the newswires. This new language-agnostic open-source specification is a complete framework implementation for describing, producing, consuming, and visualizing RESTful web services.
The Swagger framework claims to be able to simultaneously solve server, client, and documentation/sandbox needs.
It allows both developers and non-developers to interact with the API in a sandbox UI that gives insight into how the API responds to parameters and options.
According to the development team behind Swagger, its "overarching goal" is to enable client and documentation systems to update "at the same pace" as the server.
The documentation of methods, parameters, and models are tightly integrated into the server code, allowing APIs to always stay in sync.
Swagger was developed for Wordnik's own use during the development of developer.wordnik.com and the underlying system. Wordnik shows English language definitions from multiple sources, so users can see as many different takes on a word's meaning as possible.
The Swagger team calls out a couple of caveats and says that it does not currently include a suggestion for supporting multiple API versions from a client or server point of view — versioning information (both of the spec and the underlying API implementation) are declared.
"It does not tell you how to write your APIs. For example you can choose to delete an object from your system either by an HTTP
delete operation or via HTTP GET with query
param. While being a good, RESTful citizen is encouraged (and rewarded by an effective API sandbox client), it is not a prerequisite to use Swagger."
The team also says that Swagger is not trying to solve all problems for all APIs and that there will be use-cases that fall outside of the Swagger specification.