Swagger: Creating Documentation for Rest APIs

Developing an API is hard. And not just for all the efforts on design and implementation but the time dedicated to clearly document the functionality developers will use.

Swagger is an useful tool to describe, produce, consume and visualize RESTful APIs. The main objective of swagger is to tie the server side API code with the documentation and sync them.

Swagger specification is: Json, machine readable, language agnostic.

Swagger does not tell you how to write your APIs. For example you can choose to delete an object from your system either by an HTTP delete operation or via HTTP GET with query param. While being a good, RESTful citizen is encouraged (and rewarded by an effective API sandbox client), it is not a prerequisite to use Swagger.

There are many libraries in different languages to automatically generate swagger docs from comments on code.

  • Grails 2
  • Scala Play 2
  • Scalatra via swagger-support, see Swagger Guide
  • Spring MVC
  • 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

You can also 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 creating some files.