xesued / swagger-spec

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, Swager 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 ahere 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 - 1.2

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

Swagger 1.2 Specification

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.

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.

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.

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

PHP

• Swagger-PHP - a library implementing the swagger.wordnik.com specification to describe web services, operations/actions and models enabling a uniform means of producing, consuming, and visualizing RESTful web services.
• NelmioApiDocBundle - A Symphony Bundle.
• Restler - PHP framework, swagger support in 3.0.

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.

Ruby

• grape-swagger - Add Swagger compliant documentation to your grape API.
• swagger-docs - Generates Swagger files for Rails APIs with a simple DSL.
• 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.

Community-Driven Tools

These are third party tools generated by the Swagger community:

• gform-admin - An alternative UI client for Swagger.

Support

The following methods are available to obtain support for Swagger:

• The Swagger Google Group - This would normally be your first stop to get support for Swagger. Here you can find previously asked question, and ask new ones. When asking a question, please provide as much information as you can regarding the environment you use (development language, library, versions.
• The Issues tab of the respective project in GitHub. Please open feature requests and bugs here. If you're not sure you encountered a bug, or if it's a general usage question, please use the Google Group mentioned above.
• IRC! you can find us on freenode in the channel #Swagger. You can talk with us directly there.

Keep in mind that if you have an issue with a specific community-driven library, you may want to ask in their respective support channels.

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.