このブログはScalaアドベントカレンダー15日目の記事です。
こんにちは。
ShareWisエンジニアの国平です。
今日は、記念すべきShareWisリニューアル版のリリース日でした。
これまで、ShareWisはユーザ投稿型の学習コンテンツプラットフォームとしてご利用いただいていましたが、今日からは動画によるスナックラーニングサービスとして生まれ変わりました。まだ、利用できるコース数は多くはありませんが、随時追加してIT以外の分野との出合いも提供していきます。ご期待ください！！
この新ShareWisですが、お知らせにもある通り、フロントエンドは ReactNative製、サーバサイドは Scala + PlayFramework製です。
今回の記事では、フロントエンドエンジニアのJonnyとサーバサイドエンジニアの私がAPIについての情報をやり取りする際に利用しているSwaggerをPlay2.4で利用するためのTipsをご紹介します。
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
コメント