Home

What is Swagger?

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.

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 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.

How to contribute

Community contributions have made Swagger. If you are interested in contributing, please follow these simple guidelines.

1. Use the Google Group for questions. Issues should be opened if you find a problem in the product or have an enhancement request.

2. Send pull requests against the DEVELOP branch! The master is stable so sending a pull request against it should really be used when there's a terrible bug that needs to be patched. Typically, they should go against develop.

3. Supply test cases. If you don't we can't see if your code is working or not, or is broken in the future.

Why is Swagger useful?

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.

How can I make my API Swagger?

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:

• Django

• node.js with express framework

• Java/Scala JAX-RS

• RESTEasy

• Grails 2

• Scala Play 1.4

• Scala Play 2

• Scalatra via swagger-support, see Swagger Guide

• Spring MVC via swagger-springmvc

• Spring MVC via swagger4spring-web

• 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:

• Ruby

• [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:

• Swagger maven plugin

Anatomy of the Spec

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.

License

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.