OpenAPI を後入れするときの戦略
考えられるのは以下
openapi.yaml を手書きする
論外。OpenAPI の YAML/JSON はとても人間が読み書きできるものではないと思う
部分的に、たとえば nullable: false だけ書いたり消したりする以上の触り方をしたくない…
Controller の実装に swagger 対応を突っ込む( swagger_blocks + Comittee など)
理想はこれ(まずスキーマがあって、そこからテストも型定義も生成される順番)
新規プロジェクトならこういうのを選ぶと思う
ただ言うて swagger_blocks も書くのがくっそめんどいと思ってて、後入れするならもっとスモールスタート感がほしいよねと思っている
コントローラーは普通に書いて、Rack で Committee が検査するみたいな使い方は良いと思う
spec から swagger を生成する
RSpec で Request Spec を書いて実行すると example 付きでスキーマを推定してくれる
テストが網羅的でないと型は正確にならない
本当は int | null だけど int が返るときのテストしか書いてなかった場合ドキュメントが嘘になる
ただまぁ yaml を手編集しても上書きしない設計になってるらしいのでそこは人が直すと良い
型を良くするためにテストのも網羅性を上げようという圧力が発生する
Request Spec がなく Controller Spec がいっぱい残ってるプロジェクトの場合も「Request Spec を書けば書くほど API ドキュメントがまともになる(自動で)」という前向きな移行モチベーションが発生する
そういうわけで、後入れするケースでは一番最後が個人的には良いと思ってる。
もちろんこの方法には欠点もあって、↑ に述べた型の不正確さに加え、動く spec を書かないとスキーマができない( つまり実装が先なのでスキーマファースト開発ができない )という点が弱い。
フロントエンドの人が型を決めて(あるいは事前に握って)それを元にサーバーサイドの実装を…というフローを採りたい場合このアプローチは選ばないほうが良いだろう。
------
ところで OpenAPI の場合ドキュメントのホスティング方法みたいな課題もある。
アプリケーションの一部として入れる( mountable engine で /admin/swagger 生やす系 )
静的 html としてホスティングする系
個人的に、ドキュメントやプレビュー系の開発ツールがサーバーを必要とするのが嫌いで( ActionMailer::Preview 静的 html 対応しねーかな )、できるだけ静的にホスティングしたいと思っている。
ところで GitLab を使っている場合、リポジトリ内に openapi や swagger を名前に含む yaml があると Swagger UI の見た目でプレビューする機能がある。この場合ホスティングすら必要ない( GitHub にも欲しいなこれ )。
また手元で最新のドキュメントが見たい場合個人的には VSCode 拡張で済ませてしまうと楽。