勤めている会社にAPIドキュメントがなく、バックエンドはPostmanとかでAPI通信確認してたんだけど、クライアントも容易に確認できた方がいいよねっていうことで、Swagger(OpenAPI)を導入したので、そのお話。(具体的な導入手順は省くよ)
本題
方法としては、主に4つあるかなと考えていて、結果的に4を採用することにした。
1 yamlを直接書く
導入は容易なんだけど、一から手書きするのはしんどいなと言うことで、これは最終手段かなと思っていた。
2 controllerに書く
具体的には、 swagger_blocks gemとかで、そもそも最終更新が数年前なので、微妙だなぁと思ったのと、既存システムのcontrollerを書き換えるのは、結構大変そうだな。と言うことでやめた。
GitHub - fotinakis/swagger-blocks: Define and serve live-updating Swagger JSON for Ruby apps.
3 RSpecから自動で生成する(
rspec-openapi)
既存specでも自動でyamlを生成できるやつで、これは運用もしやすそうだなと思ったんだけど、既存specのカバレッジ(どのくらい網羅できてるか)によってドキュメントの質が大きく変わってしまうのと、ちょっと挙動が特殊だったりするので、やめた。
挙動については、↓あたり
RailsでOpenAPI(Swagger)を生成したくてrspec-openapiにPRを立てた話 - スタディスト Tech Blog
でも、結構導入している企業多いなという印象なのでこれでも良さそうとは思ってた。
4 RSpecから自動で生成する(
rswag)
GitHub - rswag/rswag: Seamlessly adds a Swagger to Rails-based API's
RSpecから自動生成できるという点では3と同じだけど、これは特殊な書き方をしないといけなくて、そのspecのみが生成対象となる。
これは専用の書き方に書き換えたspecのみが生成対象となるため、正しくドキュメント化したいAPIを少しずつ対応することができるので導入しやすいと思った。
ただ、ちょっと書き方に癖があるので、慣れるまでは実装工数がかかりそうだなと思ったんだけど、実際には既にあるspecをコピってきて、ちょっと書き換える。とかでいけるのでそこまでの問題ではなかった。
今後の課題として、レスポンススキーマの生成はどうにかしたいなと思ってる。
components も便利なんだけど、それすら書くのが面倒だし、実際のスキーマと異なる可能性があるので、実際のAPIレスポンスクラスを基に、rswagのレスポンススキーマが生成できるように変換する処理みたいなのを入れたいと思ってる。
おわり
最初から導入することが決まっているなら、2とかもありだと思うけど、後入れなら、3,4かなと思ってる。
正直自分は、Postmanで使っていたのでそこまで恩恵ないかもなんだけど、これで全体の開発スピードが上がったら嬉しいですね！
連続投稿5日目！yoshi!
