Home Blog Playing with Swagger...

Playing with Swagger: Using Swagger and Swagger UI with the Play framework

Lorinda Brandon
  July 30, 2015

Author: Brian Porter

For those of you who aren't familiar with Play, here's how Wikipedia describes it:

Play is an open source web application framework, written in Scala and Java, which follows the model–view–controller (mvc) architectural pattern. It aims to optimize developer productivity by using convention over configuration, hot code reloading and display of errors in the browser. … Play is heavily inspired by Ruby on Rails and Django and is similar to this family of frameworks. Play uses Java to build web applications in an environment that may be less Java Enterprise Edition-centric. Play uses no Java EE constraints. This can make Play simpler to develop compared to other Java-centric platforms.

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

5. Start the application 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 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

About me

I 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 consult​ing and pro​gram​ming, I co-founded Site​Force AG eBusi​ness Solu​tions in 1999 in Munich (München), Ger​many. This has become my home base for launching new projects and is a family-friendly location for my wife and sons. I currently work as an external CTO for Startups in the Munich area. You can read my blog at: http://www.poornerd.com

You Might Also Like