Play2.4+Swaggerでフロントエンドエンジニアとコミュニケーションする




このブログはScalaアドベントカレンダー15日目の記事です。
こんにちは。
ShareWisエンジニアの国平です。

今日は、記念すべきShareWisリニューアル版のリリース日でした。


これまで、ShareWisはユーザ投稿型の学習コンテンツプラットフォームとしてご利用いただいていましたが、今日からは動画によるスナックラーニングサービスとして生まれ変わりました。まだ、利用できるコース数は多くはありませんが、随時追加してIT以外の分野との出合いも提供していきます。ご期待ください!!

この新ShareWisですが、お知らせにもある通り、フロントエンドは ReactNative製、サーバサイドは Scala + PlayFramework製です。

今回の記事では、フロントエンドエンジニアのJonnyとサーバサイドエンジニアの私がAPIについての情報をやり取りする際に利用しているSwaggerをPlay2.4で利用するためのTipsをご紹介します。

swagger-logo

Swagger


SwaggerはREST APIドキュメントを生成するツールです。
RESTful APIの標準化を目指すOpen API Initiativeという団体が、先日立ち上がりましたが、そこではSwaggerをベースに標準化を進めていくそうです。

Swaggerの全般的な資料はこちらのスライドによくまとまっています。


Playでの利用


SwaggerをPlayに組み込んでAPIドキュメントの自動生成をする場合には、日本語だとこちらの記事が非常によくまとまっています。


しかし、この記事以降にPlayのバージョンアップなどもあり、記事のとおりにはSwaggerを導入できないので、差分についてご説明します。
まず、SwaggerのPlay Plugin/Moduleですが、こちらの記事ではSwagger-core中に含まれていると書かれていますが、ある時点から別のリポジトリに分離されています。


ただし、私がShareWisの開発を始めた時点では、このリポジトリのPlay2.4用モジュールはPlay2.4対応が不十分でした。
Play2.3まで、Controllerはobjectで実装されていましたが、 Play2.4から play-guice の利用が推奨されるようになり、 controllerをclassとして実装するようになりました。
その変更への対応が不十分だったようで、Play2.4だけは、下記のリポジトリで開発されているモジュールを利用する必要がありました。
(最近元のリポジトリにplay2.4対応のコミットが最近取り込まれているようですが、ちゃんと動くか確認する時間が取れmせんでした。また、時間のあるときに確認します。)


その辺りの経緯は、こちらのissueを確認してください。


モジュールの取得先が変わるだけで、ほとんど上記のQiitaの記事のとおりに利用できますが、routesだけは、injectionを利用するため、下記のように記載する必要があります。

GET /api-docs @pl.matisoft.swagger.ApiHelpController.getResources
GET /api-docs/pet @pl.matisoft.swagger.ApiHelpController.getResource(path = "/pet")

この点だけ気をつければ、あとはほとんど元のpluginと同じ使い方が可能です。
これで、APIドキュメントが自動生成されて、フロントエンドエンジニアとのコミュニケーションを円滑に進めることができます。

Play2.4でRESTfulなAPIサーバを開発する際には、ぜひご利用ください。

 

最後に、新しくScala製になったShareWisではScalaがどういう言語なのかを紹介するコースも用意しています。

https://share-wis.com/web/courses/217


スタッフ募集中!

株式会社シェアウィズの求人ページ




学習を冒険に変える無料学習サービスShareWis

わたし達は「知識の地図」を使ったShareWisという学習サイト及びアプリを運営しています。

Facebookページもよろしくお願いします

FacebookページではShareWisの機能・コンテンツの追加情報、学習に関するためになる情報を配信しています。



RSSとTwitterで便利に更新情報を購読できます

最新情報をRSS、Twitterで配信しています。フォローしていただけると大変便利です。
 RSSリーダーで購読する