首頁 部落格 玩轉 Swagger...

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

Lorinda Brandon
  2015 年 7 月 30 日

作者：Brian Porter

對於那些不熟悉 Play 的人，以下是 維基百科對它的描述

Play 是一個開放原始碼的 Web 應用程式框架，以 Scala 和 Java 編寫，遵循模型-檢視-控制器 (mvc) 架構模式。它旨在透過使用慣例優於組態、熱程式碼重新載入以及在瀏覽器中顯示錯誤來最佳化開發人員的生產力。… Play 受到 Ruby on Rails 和 Django 的深刻啟發，與這個框架系列相似。Play 使用 Java 在可能較少以 Java Enterprise Edition 為中心的環境中建構 Web 應用程式。Play 不使用 Java EE 約束。與其他以 Java 為中心的平台相比，這可以使 Play 的開發更簡單。

我一直在使用 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="http://localhost: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

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

原始碼

如開頭所述，我從 GitHub 上的 James Ward 的 play-rest-security 開始，並在我的分支上進行了這些修改。對於所有感興趣的人，這是原始碼：https://github.com/poornerd/play-rest-security

關於我

我從 USC（南加州大學）畢業，獲得電腦科學學位。在 10 多年的自由顧問諮詢和程式設計之後，我於 1999 年在德國慕尼黑 (München) 與人共同創立了 SiteForce AG eBusiness Solutions。這已成為我啟動新專案的基地，也是我妻子和兒子們的家庭友好地點。我目前在慕尼黑地區擔任新創公司的外部 CTO。您可以在以下網址閱讀我的部落格： http://www.poornerd.com

您可能也會喜歡