The Swagger Specification

Welcome to the Swagger Project!

The goal of Swagger™ is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via Swagger, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interfaces have done for lower-level programming, Swagger removes the guesswork in calling the service.

Use cases for machine-readable API interfaces include interactive documentation, code generation for documentation, client, and server, as well as automated test cases. Swagger-enabled APIs expose JSON files that correctly adhere to the Swagger Specification, documented in this repository. These files can either be produced and served statically, or be generated dynamically from your application.

Without going into a long history of interfaces to Web Services, this is not the first attempt to do so. We can learn from CORBA, WSDL and WADL. These specifications had good intentions but were limited by proprietary vendor-specific implementations, being bound to a specific programming language, and goals which were too open-ended. In the end, they failed to gain traction.

Swagger does not require you to rewrite your existing API. It does not require binding any software to a service--the service being described may not even be yours. It does, however, require the capabilities of the service be described in the structure of the Swagger Specification. Not all services can be described by Swagger--this specification is not intended to cover every possible use-case of a REST-ful API. Swagger does not define a specific development process such as design-first or code-first. It does facilitate either technique by establishing clear interactions with a REST API.

This GitHub project is the starting point for Swagger. Here you will find the information you need about the Swagger Specification, a simple static sample of what it looks like, and some general information regarding the project.

Current Version - 2.0

The current version of the Swagger specification is 2.0 - and you can find it here.

Swagger 2.0 Specification

This repository contains the existing Swagger 1.2 specification as well as proposals for the 2.0 version.

Structure

Each section should contain v1.2 and v2.0 folders to avoid confusion between the versions.

Please keep in mind that the other projects under Swagger use an independent version system. As such, don't confuse the version of the Swagger Specification they support and the version of that given library. For example, Swagger-Core with the version 1.3.2 supports Swagger Specification 1.2.

The Wiki

Check out the wiki for additional and relevant information about the project.

This includes:

• Static sample tutorial.
• List of known deployments.
• Revision history.

See it in Action

If you just want to see it work, check out the pet store sample.

Additional Libraries

Swagger-Group Projects

These are the projects that were created by the same people who authored the Swagger Specification:

• swagger-core - A Swagger implementation for Java/Scala. Has integration with JAX-RS (Jersey, Resteasy, CXF...), Servlets and Play Framework.
• swagger-js - A Swagger implementation for JavaScript.
• swagger-node-express - A Swagger module for node.js with express module.
• swagger-ui - A dependency-free collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.
• swagger-codegen - A template-driven engine to generate client code in different languages by parsing your Swagger documentation.

Community-Driven Language Integrations

These are third party tools generated by the Swagger community:

Clojure

• octohipster - A hypermedia REST HTTP API library for Clojure.
• ring-swagger - Swagger implementation for Ring using Prismatic Schema for data modeling and input data coercion.

ColdFusion / CFML

• swagger-docs-cfml - create swagger docs from CFML (Railo) ReST components.

Eiffel

• swagger - Swagger protocol implementation in Eiffel.

Go

• go-restful - library to build REST based Web Services using Google Go.
• Sashay - a Go code generator for REST services that expose a Swagger specification.
• beego - A framework support support auto generate swagger spec from comments
• Swagger spec generator - A swagger spec auto generator. Doesn't depends on any framework

Java

• swagger-springmvc - Integration with Spring MVC.
• swagger4spring-web - Integration with Spring MVC.
• swagger-maven-plugin - A maven build plugin which helps you generate API document during build phase.
• swagger-jaxrs-doclet - A JavaDoc Doclet that can be used to generate a Swagger resource listing suitable for feeding to swagger-ui.
• swaggerj4 - A parsing library to turn swagger specifications into POJOs.
• dropwizard-swagger - A dropwizard bundle that wraps Swagger-Core.
• swaggerapi - Creates a Swagger resource listing suitable for feeding to swagger-ui by annotating your classes and methods and handles API calls to those methods

JavaScript

• swagger-ajax-client - Swagger client to communicate with a Swagger server using XHR requests from browsers. Includes client-side validation of requests against the given Swagger spec.
• swagger-angular-client - Angular service Swagger client to communicate with a Swagger server using the Angular-specific services (such as $http). Includes client-side validation of requests against the given Swagger spec.
• swagger-client-generator - Client library generator which can be used to create framework or platform-specific Swagger clients given a transport method (e.g. swagger-angular-client or swagger-node-client).
• swagger-validate - Validation utility to validate Swagger models or requests against a given spec, useful for writing Swagger client libraries.

.Net

• ServiceStack - a high-performance .NET web services platform that simplifies the development of high-performance REST (JSON, XML, JSV, HTML, MsgPack, ProtoBuf, CSV) and WCF SOAP Web Services. Has support for Swagger integration.
• fubumvc-swagger - This project helps your FubuMVC web application generate API documentation via Swagger.
• Swashbuckle - Adds some Swagger to your WebApi.
• Swagger.Net - Library to document the ASP.NET Web API using the Swagger specification.

Node.js

• Swagger Framework - a module for creating Swagger-based apis using the standard HTTP request listener interface (including Express). It supports request normalization/validation, pluggable consumes/produces, spec validation, and more.
• swagger-jack - Express middleware to automatically create route and validate inputs from a swagger descriptor (for NodeJS).
• hapi-swagger - A Swagger interface for HAPI.
• Swagger Validation - A library to validate a request that integrates with swagger-node-express.
• swagger-node-client - Node client to communicate with Swagger servers. Includes detailed client-side validation against the API spec.
• swaggerize-express - Design-driven RESTful apis with swagger and express from @PayPalDev.
• swaggerize-hapi - Design-driven RESTful apis with swagger and hapi from @PayPalDev.
• generator-swaggerize - Yeoman generator for krakenjs/swaggerize tools from @PayPalDev.

Perl

• Raisin - A framework with a built-in Swagger support.

PHP

• Swagger-PHP - a library implementing the swagger.io specification to describe web services, operations/actions and models enabling a uniform means of producing, consuming, and visualizing RESTful web services.
• NelmioApiDocBundle - A Symfony Bundle.
• Restler - PHP framework, swagger support in 3.0.
• swagger-assert - enable to assert keys in swagger document and API response
• Swaggervel - a package for Laravel that uses Swagger-PHP and swagger-ui to auto-generate docs for your project.

Python

• django-rest-swagger - Swagger Documentation Generator for Django REST Framework
• django-tastypie-swagger - An adapter to use Swagger with django-tastypie.
• flask-restful-swagger - A Swagger spec extractor for flask-restful.
• pyramid-swagger - Convenient tools for using Swagger to define and validate your interfaces in a Pyramid webapp.
• flask-restplus - Helpers, syntaxic sugar and Swagger documentation for Flask-Restful
• pyswagger - A type-safe, dynamic, spec-compliant Swagger client.
• flex - Swagger 2.0 schema validation, and tooling for validating arbitrary request/response objects.

Ruby

• grape-swagger - Add Swagger compliant documentation to your grape API.
• swagger-docs - Generates Swagger files for Rails APIs with a simple DSL.
• swagger-blocks - Define and serve live-updating Swagger JSON for Ruby apps.
• source2swagger - Builds a swagger compliant JSON specification from annotations on the comments of your source code.

Scala

• Scalatra - see the Swagger Guide
• spray-swagger - Spray-Swagger brings Swagger support for Spray Apis.
• Api-doc - Creates swagger docs from easily readable ascii text placed in the code. Depends on playframework, but may also be used in other frameworks.

Community-Driven Tools

These are third party tools generated by the Swagger community:

• gform-admin - An alternative UI client for Swagger.
• swagger-cli-client - Command-line interface generator to communicate with Swagger servers.

License

Copyright 2014 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

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.