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.
"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"
api.version="1.0" swagger.api.basepath="http://localhost:9000"
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)
@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)); } }
<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>
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