Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services. The overarching goal of Swagger 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. With Swagger, deploying managing, and using powerful APIs has never been easier.
Who is responsible for Swagger?
Both the specification and framework implementation are initiatives from Wordnik. Swagger was developed for Wordnik's own use during the development of developer.wordnik.com and the underlying system. Swagger development began in early 2010—the framework being released is currently used by Wordnik’s APIs, which power both internal and external API clients.
Why is Swagger useful?
The Swagger framework simultaneously solves server, client, and documentation/sandbox needs. As a specification, it is language-agnostic. It also provides a long runway into new technologies and protocols beyond REST.
With Swagger's declarative resource specification, clients can understand and consume services without knowledge of server implementation or access to the server code. The Swagger UI framework allows both developers and non-developers to interact with the API in a sandbox UI that gives clear insight into how the API responds to parameters and options.
Swagger happily speaks both JSON and XML, with additional formats in the works.
How is Swagger implemented?
As a specification, Swagger is language-agnostic. But since a spec without a usable implementation has limited immediate value, Wordnik has released Swagger implementations in Scala, Java, and HTML5. Client generators are currently available for Scala, Java, Javascript, Ruby, PHP, and Actionscript 3. More client support is underway.
What is Swagger not trying to solve?
Swagger 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.
Swagger is not trying to solve all problems for all APIs—there will be use-cases that fall outside of the Swagger specification. For this reason, Swagger is an improvement on existing specs like WSDL 2.0 and WADL which must support legacy systems in order to be generally accepted.
The Swagger Specification: https://github.com/wordnik/swagger-core/wiki
Swagger Demo: http://petstore.swagger.wordnik.com/
Downloads: https://github.com/wordnik/swagger-core/wiki/Downloads
