首页 博客 使用 Swagger...

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

Lorinda Brandon
  2015 年 7 月 30 日

作者：Brian Porter

对于那些不熟悉 Play 的人来说，以下是 维基百科对其的描述

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

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

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

操作步骤

1. 首先，将依赖项添加到您的 build.sbt 中。通过参考 GitHub 问题 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

源代码

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

关于我

我毕业于南加州大学 (University of Southern California)，获得计算机科学学位。在进行了 10 多年的自由咨询和编程之后，我于 1999 年在德国慕尼黑 (München) 共同创立了 SiteForce AG eBusiness Solutions。这里已成为我启动新项目的大本营，并且是我的妻子和儿子们的家庭友好型地点。我目前在慕尼黑地区担任初创公司的外部首席技术官。您可以在以下网址阅读我的博客：http://www.poornerd.com

您可能还喜欢