---
title: "It’s easy to document your Play Framework REST API with Swagger"
date: 2015-08-06T21:08:59+00:00
author: "poornerd"
canonical: https://www.poornerd.com/2015/08/06/its-easy-to-document-your-play-framework-rest-api-with-swagger/
source: Raw Markdown twin of the HTML article; content is the original source.
---
_This post originally ran on <a href="http://swagger.io/playing-with-swagger-using-swagger-and-swagger-ui-with-the-play-framework/" onclick="javascript:pageTracker._trackPageview('/outbound/article/swagger.io');" target="_blank">http://swagger.io (7/30/2015)</a>_

I having been using <a href="https://www.playframework.com/" onclick="javascript:pageTracker._trackPageview('/outbound/article/www.playframework.com');" target="_blank">Play Framework</a> as a Java-based, lightning-fast REST backend framework for several projects. Later, I was was excited to find <a href="http://swagger.io" onclick="javascript:pageTracker._trackPageview('/outbound/article/swagger.io');" target="_blank">Swagger</a> 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 <a href="http://www.jamesward.com" onclick="javascript:pageTracker._trackPageview('/outbound/article/www.jamesward.com');" target="_blank">James Ward</a> . James’ project is located on <a href="https://github.com/jamesward/play-rest-security" onclick="javascript:pageTracker._trackPageview('/outbound/article/github.com');" target="_blank">GitHub so you should pull it</a> 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: <a href="https://github.com/swagger-api/swagger-core/issues/550" onclick="javascript:pageTracker._trackPageview('/outbound/article/github.com');" target="_blank">https://github.com/swagger-api/swagger-core/issues/550</a>.

<pre class="brush: plain; title: ; notranslate" title="">"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"
</pre>

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:

<pre class="brush: plain; title: ; notranslate" title="">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)

</pre>

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

<pre class="brush: plain; title: ; notranslate" title="">@Api(value = "/api/todos", description = "Operations with Todos") 
@Security.Authenticated(Secured.class) 
public class TodoController extends Controller {
</pre>

Then the Annotations for the GET and POST methods:

<pre class="brush: plain; title: ; notranslate" title="">@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&lt;models.Todo&gt; 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)); 
     } 
}
</pre>

5. 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: <a href="https://github.com/poornerd/play-rest-security" onclick="javascript:pageTracker._trackPageview('/outbound/article/github.com');" target="_blank">https://github.com/poornerd/play-rest-security</a> 

**NOTE: meanwhile, James Ward has approved my pull request to add these changes to his project &#8211; <a href="https://github.com/jamesward/play-rest-security" onclick="javascript:pageTracker._trackPageview('/outbound/article/github.com');" target="_blank">GitHub so you should pull it</a>**