ホーム ブログ Swagger と遊ぶ...

Swagger と遊ぶ: Play フレームワークで Swagger と Swagger UI を使う

ロリンダ・ブランドン
  2015年7月30日

著者: Brian Porter

Play をご存じない方のために、Wikipedia の説明を以下に示します。

Play は、Scala と Java で書かれたオープンソースのウェブアプリケーションフレームワークであり、モデル・ビュー・コントローラー (MVC) アーキテクチャパターンに従っています。設定よりも規約、ホットコードリロード、ブラウザでのエラー表示を使用することで、開発者の生産性を最適化することを目指しています。… Play は Ruby on Rails と Django に強く影響を受けており、この種のフレームワークに似ています。Play は、Java Enterprise Edition 中心ではない環境でウェブアプリケーションを構築するために Java を使用します。Play は Java EE の制約を一切使用しません。これにより、Play は他の Java 中心プラットフォームと比較して開発が簡単になります。

私は、いくつかのプロジェクトで、Java ベースの超高速 REST バックエンドフレームワークとしてPlay Framework を使用しています。その後、Swagger を見つけて興奮し、いくつかのプロジェクトに統合しようとしました。最初に苦労したので、私の経験を共有し、すぐに成功するための手順を説明する「ハウツー」記事を作成することが有用だと思いました。

物事を単純化するために、私はJames Ward によって作成された既存の Play Framework、Java、JPA、REST プロジェクトから始めました。James のプロジェクトは GitHub にあるので、このハウツーを始める前にプルしておくべきです。

ハウツーの手順

1. まず、build.sbt に依存関係を追加します。サンプルプロジェクトで使用されている Play Framework 2.3.0 のバージョンと swagger-core の間の依存関係の問題は、GitHub issue 55o (https://github.com/swagger-api/swagger-core/issues/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"

2. 設定 application.conf にこれを追加します

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

3. routes ファイルに api-docs ルートを追加します

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. ToDoController に Swagger アノテーション (@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

私について

私は USC (南カリフォルニア大学) をコンピュータサイエンスの学位で卒業しました。10 年以上のフリーランスのコンサルティングとプログラミングを経て、1999 年にドイツのミュンヘンで SiteForce AG eBusiness Solutions を共同設立しました。これが私の新しいプロジェクトを立ち上げる拠点となり、妻と息子たちにとって家族に優しい場所です。現在、ミュンヘン地域のスタートアップで外部 CTO として働いています。私のブログは以下で読むことができます: http://www.poornerd.com

こちらもおすすめ