beautify thy api

APIs should be beautiful. On the inside & the outside.

API Structure

Swagger allows you to describe the structure of your APIs so that machines can read them.

The ability of APIs to describe their own structure is the root of all awesomeness in Swagger. Why is it so great? Well, by reading your API’s structure we can automatically build beautiful and interactive API documentation. We can also automatically generate client libraries for your API in many languages and explore other possibilities like automated testing.

Swagger does this by asking your API to return a JSON that contains a detailed description of your entire API. This JSON is essentially a resource listing of your API which adheres to Swagger Specification. The specification asks you to include information like:

  • What are all the operation that your API supports?
  • What are your API’s parameters and what does it return?
  • Does your API need some authorization?
  • Even fun things like terms, contact information and license to use the API.

Expose your API

So how do we get your APIs to return a swagger compliant resource listing?

Well, you can handcode it. But that really isn’t much fun.

How about if your server could automatically generate it for you? That is indeed possible and is supported for a number of technologies. The people who wrote swagger specification created support for a few (in bold below). The amazing swagger community has built support for a number of server side technologies to automate generation of swagger resource listing.

Click on ‘Swaggerize your service’ above for in depth tutorials on some of these technologies. A more complete listing of platforms and technolgies which work with Swagger is below:

Platform Technology
Java JAX-RS (Jersey, Resteasy, CXF),
Play Framework
Spring using swagger-springmvc or swagger4spring-web
Scala Scalatra
Play Framework
Clojure octohipster
Node.js Express
Express with swagger-jack
Standard HTTP/Express, Spec validation etc via Swagger Framework
ColdFusion / CFML swagger-docs-cfml
Go go-restful
.Net ServiceStack
Python Django
Django Tastypie
Ruby grape
From source
Misc Alternative Swagger UI