It’s easy to document your Play Framework REST API with Swagger

• This post orig­i­nally ran on http://​swag​ger​.io (7/30/2015)

I hav­ing been using Play Frame­work as a Java-based, lightning-fast REST back­end frame­work for sev­eral projects. Later, I was was excited to find Swag­ger and worked to inte­grate it into a few projects. As I strug­gled with it the first time, I thought it would be use­ful to share my expe­ri­ence and cre­ate a “how-to” arti­cle describ­ing the steps to suc­ceed quickly.

In order to sim­plify things, I have started off with an exist­ing Play Frame­work, Java, JPA, REST project cre­ated by James Ward . James’ project is located on GitHub so you should pull it before you start with this how-to.

How-To Steps

1. First, add the depen­den­cies to your build.sbt. I was able to solve a depen­dency prob­lem with the ver­sion of Play Frame­work 2.3.0 used in the sam­ple project and swagger-core by refer­ring to GitHub issue 55o: https://​github​.com/​s​w​a​g​g​e​r​-​a​p​i​/​s​w​a​g​g​e​r​-​c​o​r​e​/​i​s​s​u​e​s​/​550.

   "com.wordnik" %% "swagger-play2" % "1.3.12" exclude("org.reflections", "reflections"), 
   "org.reflections" % "reflections" % "0.9.8" notTransitive (), 
   "org.webjars" % "swagger-ui" % "2.1.8-M1"

2. Add this to your configu­ra­tion application.conf :
    
   api.version="1.0" swagger.api.basepath="http://localhost:9000"
3. Add the api-docs routes to the routes file:

   GET / controllers.Assets.at(path="/public", file="index.html")
   
   GET /api-docs controllers.ApiHelpController.getResources
   
   POST /login controllers.SecurityController.login() POST /logout controllers.SecurityController.logout()
   
   GET /api-docs/api/todos controllers.ApiHelpController.getResource(path = "/api/todos") 
   GET /todos controllers.TodoController.getAllTodos() 
   POST /todos controllers.TodoController.createTodo()
   
   # Map static resources from the /public folder to the /assets URL path 
   GET /assets/*file controllers.Assets.at(path="/public", file)

4. Add Swag­ger Anno­ta­tions to the ToDoCon­troller ( @Api ):

   @Api(value = "/api/todos", description = "Operations with Todos") 
   @Security.Authenticated(Secured.class) 
   public class TodoController extends Controller {

   Then the Anno­ta­tions for the GET and POST methods:

   @ApiOperation(value = "get All Todos",
        notes = "Returns List of all Todos",
        response = Todo.class, 
        httpMethod = "GET") 
   public static Result getAllTodos() { 
        return ok(toJson(models.Todo.findByUser(SecurityController.getUser()))); 
   }
   @ApiOperation( 
        nickname = "createTodo", 
        value = "Create Todo", 
        notes = "Create Todo record", 
        httpMethod = "POST", 
        response = Todo.class
    ) 
   @ApiImplicitParams( 
        { 
             @ApiImplicitParam( 
                  name = "body", 
                  dataType = "Todo", 
                  required = true, 
                  paramType = "body", 
                  value = "Todo" 
             ) 
        } 
   ) 
   @ApiResponses( 
             value = { 
                     @com.wordnik.swagger.annotations.ApiResponse(code = 400, message = "Json Processing Exception") 
             } 
   ) 
   public static Result createTodo() { 
        Form<models.Todo> form = Form.form(models.Todo.class).bindFromRequest(); 
        if (form.hasErrors()) { 
            return badRequest(form.errorsAsJson()); 
        } 
        else { 
             models.Todo todo = form.get(); 
             todo.user = SecurityController.getUser(); 
             todo.save(); 
             return ok(toJson(todo)); 
        } 
   }

5. Start the appli­ca­tion and go to this URL in your browser:
    
   http://localhost:9000/assets/lib/swagger-ui/index.html?/url=http://localhost:9000/api-docs

Source Code

As men­tioned in the begin­ning, I started with James Ward’s play-rest-security on githuband made these mod­ifi­ca­tions on my fork. For all who are inter­ested, here is the source code:

• https://​github​.com/​p​o​o​r​n​e​r​d​/​p​l​a​y​-​r​e​s​t​-​s​e​c​u​r​ity

NOTE: mean­while, James Ward has approved my pull request to add these changes to his project — GitHub so you should pull it