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

This post originally ran on http://swagger.io (7/30/2015)

I having been using Play Framework as a Java-based, lightning-fast REST backend framework for several projects. Later, I was was excited to find Swagger and worked to integrate it into a few projects. As I struggled with it the first time, I thought it would be useful to share my experience and create a “how-to” article describing the steps to succeed quickly.

In order to simplify things, I have started off with an existing Play Framework, Java, JPA, REST project created 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 dependencies to your build.sbt. I was able to solve a dependency problem with the version of Play Framework 2.3.0 used in the sample project and swagger-core by referring to GitHub issue 55o: https://github.com/swagger-api/swagger-core/issues/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"

1. Add this to your configuration application.conf :

api.version="1.0" swagger.api.basepath="http://localhost:9000"

1. 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)

1. Add Swagger Annotations to the ToDoController ( @Api ):

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

Then the Annotations 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)); 
     } 
}

1. Start the application and go to this URL in your browser:

<a href="http://localhost:9000/assets/lib/swagger-ui/index.html?/url=http://localhost:9000/api-docs" onclick="javascript:pageTracker._trackPageview('/outbound/article/localhost:9000');" target="_blank">http://localhost:9000/assets/lib/swagger-ui/index.html?/url=http://localhost:9000/api-docs</a>

Source Code

As mentioned in the beginning, I started with James Ward’s play-rest-security on githuband made these modifications on my fork. For all who are interested, here is the source code: https://github.com/poornerd/play-rest-security

NOTE: meanwhile, James Ward has approved my pull request to add these changes to his project – GitHub so you should pull it

If you made it this far, you may as well follow me on LinkedIn: Follow Brian Porter

---