玩转 Swagger：在 Play 框架中使用 Swagger 和 Swagger UI

2015 年 7 月 30 日

作者：Brian Porter

Play 是一个用 Scala 和 Java 编写的开源 Web 应用程序框架，它遵循模型-视图-控制器 (MVC) 架构模式。它旨在通过约定优于配置、热代码重载和在浏览器中显示错误来优化开发人员的工作效率。… Play 深受 Ruby on Rails 和 Django 的启发，与这类框架相似。Play 使用 Java 在一个可能不那么以 Java 企业版为中心的环境中构建 Web 应用程序。Play 不受 Java EE 约束。这使得 Play 与其他以 Java 为中心的平台相比更易于开发。

我一直在使用 Play Framework 作为基于 Java 的、极速 REST 后端框架，用于多个项目。后来，我很高兴地发现了 Swagger，并努力将其集成到几个项目中。当我第一次遇到困难时，我认为分享我的经验并撰写一篇“操作指南”文章来描述快速成功的步骤会很有用。

为了简化事情，我从 James Ward 创建的一个现有 Play Framework、Java、JPA、REST 项目开始。James 的项目在 GitHub 上，因此在开始本操作指南之前，您应该拉取它。

操作步骤

1. 首先，将依赖项添加到您的 build.sbt。通过参考 GitHub issue 55o：https://github.com/swagger-api/swagger-core/issues/550，我解决了示例项目中使用的 Play Framework 2.3.0 版本与 swagger-core 之间的依赖问题。

"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. 将此添加到您的配置 application.conf

 api.version="1.0" swagger.api.basepath="https://:9000"

3. 将 api-docs 路由添加到 routes 文件

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. 将 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)); 
     } 
}

5. 启动应用程序并在浏览器中访问此 URL

https://:9000/assets/lib/swagger-ui/index.html?/url=https://:9000/api-docs

源代码

如开头所述，我从 James Ward 在 GitHub 上的 play-rest-security 项目开始，并在我的分支上进行了这些修改。对所有感兴趣的人，源代码在此：https://github.com/poornerd/play-rest-security

关于我
我毕业于南加州大学 (University of Southern California)，获得计算机科学学位。在超过 10 年的自由职业咨询和编程工作之后，我于 1999 年在德国慕尼黑 (München) 共同创立了 SiteForce AG 电子商务解决方案公司。这里已成为我启动新项目的根据地，也是我和妻子、儿子们宜居的家庭友好型城市。我目前在慕尼黑地区担任创业公司的外部 CTO。您可以在我的博客上阅读更多内容： http://www.poornerd.com