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

Subscribe
Notify of
guest

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

1 Comment
Oldest
Newest Most Voted
Inline Feedbacks
View all comments
vijay
vijay
8 years ago

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

Back to top button