Wednesday, September 23, 2015

Play-Swagger: a Swagger spec generator for REST APIs built with Play Framework


I am pleased to release play-swagger  - a Swagger spec generator for REST APIs built with Play Framework.
It generates swagger specs from play route files and case class reflections without the need for any code annotation.
The main principles we follow when designing this library are:
  1. No code pollution (e.g. annotation)
  2. DRY (extract as much information from the code as possible)
  3. When documenting an endpoint, it should be just swagger specification that you need to write. You shall not need to learn another API or spec format.
  Which translate to following features we implemented:
  1. Write your swagger specification in your routes files as comments (json or yml)
  2. Reference your case classes in your swagger spec and play-swagger will generate definitions
  3. Override anything in either the swagger spec in comment or the base swagger spec file.

Here is a simple example that demonstrates how iheart/play-swagger works.
In a cards.routes which is referenced in routes as

->  /api/cards    cards.Routes
You write the following swagger spec in comment.

###
# summary: create a card 
# responses:
#   200:
#     description: success
#     schema:
#      $ref:'#/definitions/com.iheart.api.Protocol.CardCreated'
###
POST      /users/:profileId/contexts/:contextName/cards       controllers.api.Cards.createCard(profileId: Int, contextName: Option[String])
Note that everything in the comment is just standard swagger definition, and it $refs to a case class CardCreated, which is defined in a Protocol object, which then references another case class Card. Here is the source code:

package com.iheart.api
object Protocol {
  case class CardCreated(card: Card)
  case class Card(id: Int, name: String)
}
With the minimum swagger def written in the routes file as comments, the result swagger specs will look like:
image
For more detail, please go to the project page: http://iheartradio.github.io/play-swagger/
Any feedback/contribution will be greatly appreciated!