Enterprise Java

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

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") 
    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()))); 
         nickname = "createTodo", 
         value = "Create Todo", 
         notes = "Create Todo record", 
         httpMethod = "POST", 
         response = Todo.class
                   name = "body", 
                   dataType = "Todo", 
                   required = true, 
                   paramType = "body", 
                   value = "Todo" 
              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(); 
              return ok(toJson(todo)); 
  5. Start the appli­ca­tion and go to this URL in your browser:

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:

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

Want to know how to develop your skillset to become a Java Rockstar?

Join our newsletter to start rocking!

To get you started we give you our best selling eBooks for FREE!


1. JPA Mini Book

2. JVM Troubleshooting Guide

3. JUnit Tutorial for Unit Testing

4. Java Annotations Tutorial

5. Java Interview Questions

6. Spring Interview Questions

7. Android UI Design


and many more ....


Receive Java & Developer job alerts in your Area

I have read and agree to the terms & conditions


Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

1 Comment
Newest Most Voted
Inline Feedbacks
View all comments
7 years ago

Getting the following error while resolving dependencies.

[warn] ::::::::::::::::::::::::::::::::::::::::::::::
[warn] ::::::::::::::::::::::::::::::::::::::::::::::
[warn] :: com.wordnik#swagger-play2_2.10;1.3.12: not found
[warn] :: org.webjars#swagger-ui;2.1.8-M1: not found

Back to top button