Swaggerを使用したPlayフレームワークのドキュメント化
swaggerモジュールをセットアップするための元のソース
Play Frameworkは、以前Typesafeと呼ばれていた会社（現在はLightbend）のJavaおよびScalaプログラミング言語用のMVC Webフレームワークです。
ウェブサイト：
プレイフレームワーク
Habrからの記事：
Playでの作業の印象！ フレームワーク2.1 + Java
ウィキ
プレイ（フレームワーク）
プログラマーノート
Playフレームワーク-あなたがそれについて知りたいと思っていたが、何らかの理由で尋ねることを恐れていたすべて
Swaggerは、設計と文書化からテストと展開まで、API開発ライフサイクル全体にわたるツールのホストです。
ウェブサイト：
Sw歩
Habrからの記事：
＃マイクロサービスのドキュメント
RESTful APIを記述するための3つの最高のツール
wiki：
Openapi
Swagger（ソフトウェア）
導入から離れて、オンザフライで生成されるAPIドキュメントのインストールを開始できます。
デモンストレーションのために、2番目のバージョンのPlayフレームワークを使用します： Play 2
Swaggerモジュール
API仕様の自動生成には、 swagger-play2モジュールが必要です
Swagger UI
オフィスで。 Swagger.io WebサイトはSwagger UIを提供します。これはjson形式のSwagger仕様を受け入れ、APIの学習、実験、および理解のための動的なWebインターフェースを生成します。
Playをカスタマイズする
それでは、swaggerモジュールの統合を始めましょう。 テストには、Play Frameworkバージョン2.6.3
build.sbt
アセンブリファイルに依存関係としてプラグインを追加します
libraryDependencies += "io.swagger" %% "swagger-play2" % "1.6.0"
-
conf/application.conf
でSwaggerモジュールを接続しconf/application.conf
play.modules.enabled += "play.modules.swagger.SwaggerModule" api.version = "v1" // Specify the api version.
conf/application.conf
に設定を追加して、Swagger仕様の追加フィールドを自動生成できます。
文書化API
- Swaggerアノテーションは
io.swagger.annotations
パッケージで利用可能です - Swaggerアノテーションは、コントローラークラスのAPIをドキュメント化するために使用されます。
以下にサンプルコードを示します。 次のコードをコントローラークラスに追加します。
@Api(value = "Example Controller", produces = "application/json")
ドキュメントを追加する必要があるメソッドごとに、次の注釈を定義する必要があります。
標準の応答クラスは既に提供されています。ここではResponse.class
です。
@ApiOperation(value = "Get API", notes = "Get list of id & values.", response = Response.class)
APIが返すことができる追加の応答ごとに、次の注釈を追加できます。
@ApiResponses({ @ApiResponse(code = 403, message = "Invalid Authorization", response = ErrorStatus.class), @ApiResponse(code = 500, message = "Internal Server Error", response = ErrorStatus.class) })
コントローラーメソッドのパラメーターは、次のように追加できます。
@ApiOperation(value = "Get User", response = User.class) public Promise<Result> getUser( @ApiParam(value = "User Id", name = "userId") String userId){ User user = getUser(userId); return ok(user); }
ルート
conf/routes
設定ファイルにルートを追加することで、自動生成されたSwagger仕様にアクセスできますconf/routes
GET /docs/swagger.json controllers.ApiHelpController.getResources
これで、 /docs/swagger.json
からSwagger仕様に到達できます
Swagger UIをPlayフレームワークに追加
Swagger UIはHTML / JSを備えた動的なフロントエンドであるため、主にNginxまたはhttpdを介して提供できます。
または、playフレームワークからSwagger UIを提供することもできます。
また、APIとSwagger UIが異なるドメインにある場合に発生する可能性があるCORSエラーの問題も解決します。
Swagger UI 配布キットをPlayプロジェクトの/public/swagger-ui
にコピーします。
ルートの設定ファイルで、次のディレクトリを追加します
GET /docs/ controllers.Assets.at(path="/public/swagger-ui",file="index.html") GET /docs/swagger.json controllers.ApiHelpController.getResources GET /docs/*file controllers.Assets.at(path="/public/swagger-ui",file)
アプリケーションのルートにあるSwaggerのデフォルト仕様に仕様をリダイレクトする場合は、このルートをルート構成に追加します。
GET / controllers.Default.redirect(to = "/docs/")
index.html
を更新して、Swagger仕様へのリンクを変更します。
と
var url = window.location.search.match(/url=([^&]+)/); if (url && url.length > 1) { url = decodeURIComponent(url[1]); } else { url = "http://petstore.swagger.io/v2/swagger.json"; }
に
var url = window.location.search.match(/url=([^&]+)/); if (url && url.length > 1) { url = decodeURIComponent(url[1]); } else { url = "swagger.json"; }
APIを調べる
sbt
して起動したら、 http://localhost:9000/docs/
にアクセスして、 Swagger UIがライブで動作していることを確認します。
よし
- Swagger Specialの使用は、APIを使用するすべての人がAPIと効果的に通信できるように非常にシンプルになっています。
- Swagger仕様からクライアントコードを自動的に生成することで、APIの消費とテストが非常に簡単になりました。
まだ十分ではない
Swagger UIにはいくつかの問題があります。
- 時々、ページをリロードして再度機能させる必要があります。
- APIサービスへの接続がない場合、UIは明示的にそう言うことはできません。
- APIリンクパスプレフィックスは、現在Swagger UIでは処理されません。
- Swagger仕様の生成には、正しく実装されていない（完全ではない）セキュリティ構成が含まれています。
- おそらく、最新バージョンのサポートには遅れがあるため、Play Frameworkのメジャーバージョンを使用する必要があります。
合計
Total Swagger Spec / UIは、任意のAPIへのアクセスを記述および提供するための優れたツールです。