使用Swagger轻松记录您的Play Framework REST API

该帖子最初在http：// swag ger.io（7/30/2015）上发布

我一直在将Play Framework用作几个项目的基于Java的，快速的REST后端框架。后来，我很高兴找到Swagger，并努力将其集成到几个项目中。在我第一次挣扎时，我认为分享经验并撰写一篇“如何做”的文章来描述快速成功的步骤将很有用。

为了简化操作，我开始使用James Ward创建的现有Play框架，Java，JPA，REST项目。 James的项目位于GitHub上，因此在开始此方法之前，应先将其拉出。

操作步骤

首先，将依赖项添加到build.sbt中。我可以通过参考GitHub问题55o解决示例项目中使用的Play Framework 2.3.0版本和swagger-core的依赖问题： https：// g g e r-p i / s w g g e r-c o r e / i你/ 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"
```
将此添加到您的配置application.conf中：

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

将api-docs路由添加到路由文件：

GET / controllers.Assets.at(path="/public", file="index.html")GET /api-docs controllers.ApiHelpController.getResourcesPOST /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)

将Swagger注释添加到ToDoController（@Api）：

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

然后是GET和POST方法的注释：

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