-
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
-
Scalatra via swagger-support, see Swagger Guide
-
ServiceStack .net/MONO
-
fubumvc-swagger .net Fubumvc
-
Swashbuckle .net framework
-
Swagger.net .net integration from Mike Trionfo
-
Swagger-PHP PHP Composer
-
Symfony 2 Bundle
-
Restler PHP framework, swagger support in 3.0
-
grape-swagger for Ruby
-
django-tastypie-swagger for Python/Django
-
Octohipster for Clojure
-
go-restful for Golang
-
swagger-docs for Rails
You can generate or manually write simple, static JSON documents which describe your existing API. That means you can benefit from the swagger-ui and swagger-codegen without doing anything to your server other than creating some files. They don't even need to exist on the same server. Some known implementations include:
-
[JAX-RS & Javadoc] (https://github.com/ryankennedy/swagger-jaxrs-doclet)
Besides, you can generate your custom API documents without starting any servers, just during build phase by using a simple maven plugin:
The specification is in two parts--the Resource Listing and the API Declaration. 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
The swagger software and specification are both licensed under the Apache License, Version 2.0.
Copyright 2013 Reverb Technologies, Inc.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at [apache.org/licenses/LICENSE-2.0] (http://www.apache.org/licenses/LICENSE-2.0.html).
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.