-
Notifications
You must be signed in to change notification settings - Fork 2.2k
Home
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 can be tightly integrated into the
server code, allowing APIs to always stay in sync.
Both the specification and framework implementation are initiatives from Wordnik. Swagger was developed for Wordnik's own use during the development of http://developer.wordnik.com/docs and the underlying http://api.wordnik.com/v4. 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.
The Swagger framework simultaneously addresses server, client, and documentation/sandbox needs for REST APIs. As a specification, it is language-agnostic. It also provides a long runway into new technologies and protocols beyond HTTP.
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.
There are a number of different ways. If you're impatient you can skip directly to the tutorials
You can use the swagger-core framework, which gives you everything you need to implement a Swagger server using node.js, Java or scala using several different REST frameworks.
You can use or develop a framework for automatically generating the Swagger specification. Some known server implementations include:
node.js with express framework
fubumvc-swagger .net Fubumvc
Restler PHP framework, swagger support planned in 3.0
You can generate or manually write simple, static JSON documents which describe your existing API. That means you can benefit from the http://github.com/wordnik/swagger-ui and http://github.com/wordnik/swagger-codegen without doing anything to your server other creating some files. They don't even need to exist on the same server. One example of a swagger-spec generator is here:
https://github.com/solso/source2swagger (ruby)
The specification is in two parts--the Resource Listing and the API Description. The Resource Listing contains an inventory of APIs available on the server as well as paths to the description of the APIs.
See Resource Listing and API Declaration