Home » Java » Enterprise Java » It’s easy to document your Play Framework REST API with Swagger

About Brian Porter

Brian Porter

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") 
    @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:

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

(0 rating, 0 votes)
You need to be a registered member to rate this.
1 Comment Views Tweet it!
Do you want to know how to develop your skillset to become a Java Rockstar?
Subscribe to our newsletter to start Rocking right now!
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 ....
I agree to the Terms and Privacy Policy

1
Leave a Reply

avatar
1 Comment threads
0 Thread replies
0 Followers
 
Most reacted comment
Hottest comment thread
1 Comment authors
vijay Recent comment authors

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

  Subscribe  
newest oldest most voted
Notify of
vijay
Guest
vijay

Getting the following error while resolving dependencies.

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