Posted at
WACULDay 6

redocup で Swagger の API ドキュメントをシュッと表示する

More than 1 year has passed since last update.

WACUL Advent Calendar 2016 の6日目は、今年の9月から WACUL でサーバーサイドエンジニアをしている @zoncoen が担当します。


Swagger

WACUL では、API の定義を JSON Schema で記述し、その定義から内製のツールを用いてコードを自動生成することで API の実装を行ってきました。しかし昨年 Swagger をベースに RESTful API の記述標準化を目指す Open API Initiative が発足され、Swagger がスタンダードになっていくのではないかということで( ほんとか? ) API 定義の記述を Swagger に移行し、コード生成ツールなどのエコシステムもオープンソースのものを利用するように置き換えをすすめています。

参考: RESTful APIの記述標準化を目指す「Open API Initiative」をマイクロソフト、Google、IBMらが立ち上げ。Swaggerをベースに


Swagger UI

API 仕様からコードを自動生成するとはいえすべてのコードが生成されるわけではないので、もちろん自分たちでコードを書くわけですが、そうすると API の仕様を確認したくなったりするわけです。そのような場合、JSON や YAML をそのまま読むのではなく、一般的には Swagger UI などで HTML に変換して読むことになるかと思います。しかし手元のブランチの API 定義をサクッと確認したいだけなのに、Swagger UI をダウンロードして HTML / JSON と一緒にサーバーに配置してサーバー立ち上げるとかめんどくさいですよね?何も考えずにコマンド叩いたらローカルにサーバーがたってそこにアクセスすれば見れる、みたいなカジュアルなものがあると嬉しい。


Redocup

というわけでつくりました。

redocup - Simple way to serve OpenAPI/Swagger-generated API reference documentation with ReDoc.

Redoc という JavaScript のライブラリをつかった Swagger API Document を閲覧できるサーバーを起動するためのコマンドです。npm に公開しているので、npm install -g redocup でインストールできます。これを使うと redocup spec.json とするだけでサーバーが起動するので、http://localhost:5000/ をひらけばドキュメントを見ることができます。

ちなみに redocup には Browsersync を利用した watch option を用意しているので、Swagger の定義ファイルを編集するときに使うと編集する度に自動でリロードされて便利です。

redocup watch option.gif


まとめ

楽に Swagger の定義を HTML ドキュメントとして閲覧するためのコマンド redocup を紹介しました。

Open API Initiative が立ち上げられて1年以上たちましたが、Swagger 特に盛り上がってる感なくて関連ツールもイケてなかったりして、誰も使ってないのでは…と思うときがあったりなかったり。使ってる方がいたらぜひお話してみたいものです。