my thoughts on programming and other nerdy stuff

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"

2. Add this to your configuration 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 Swagger Annotations to the ToDoController ( @Api ):

@Api(value = "/api/todos", description = "Operations with Todos") 
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()))); 
     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 application and go to this URL in your browser:

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 have read this far, you may as well follow me on Twitter:

Author: poornerd

Tech­nol­o­gist, Entre­pre­neur, Vision­ary, Pro­gram­mer :: Grad­u­ated from USC (Uni­ver­sity of South­ern Cal­i­for­nia) with a degree in Com­puter Sci­ence. After 10+ years of free­lance con­sult­ing and pro­gram­ming, he co-founded Site­Force AG eBusi­ness Solu­tions in 1999 in Munich (München), Ger­many.

Leave a Reply

Required fields are marked *.