Swagger を試してみた

そろそろ手書きで API の仕様を作るのやめたいと思って swagger を試してみました。

swagger は別に単一のソフトではなくて、 Swagger Spec という仕様で書かれた定義書を 元にドキュメントを書いたり、コードを生成したりできるものみたいです。

Swagger Editor

オンライン のがありますが、 docker 版もあるのでそちらでやりました。

$ docker pull swaggerapi/swagger-editor
$ docker run -d -p 80:8080 swaggerapi/swagger-editor

で localhost にブラウザでアクセスすればよいです。 定義を書いたら右側にドキュメントが表示されて、 さらに上のメニューから、モックとかクライアントを 作ってくれます。

Swagger UI

定義ファイルを読み込んでドキュメントを生成してくれるツールです。 デフォルトでは Swagger Editor と同じデザインですが、 カスタマイズもできるもよう。

まとめ

最初の学習コストはあるけど、導入した方がいいと思いました。 この yaml を git に入れておけば仕様決めの段階から プルリクで議論できるし、CI ツールで マージ→仕様書更新まで自動化できると思います。

ただ、そのままでは yaml の分割に対応してないんですが、 いくつかツールがあるみたいなので、なんとかなりそうな気がします。