OpenAPI + Rails の戦略を考えていたが素直にOpenAPI schema書くのが良さそうという結論に至ったメモ

ASP.NET Core では Swashbuckle を使うことで
routing と Controller の定義から OpenAPI Schema を自動生成してくれて
Swagger UI も表示できるので Rails でも同じことをやりたかった

参考：
Swashbuckle と ASP.NET Core の概要
https://docs.microsoft.com/ja-jp/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-6.0&tabs=visual-studio-code

結論からいうと、実現できるgemはない。

というか、Swashbuckle が特殊なだけで
OpenAPI 仕様としては Schema First Development （スキーマ駆動開発）で考える人が多いみたい
※個人の感想です

Swashbuckle は Code First Development 的なアプローチ

fotinakis / swagger-blocks
https://github.com/fotinakis/swagger-blocks

というものがあり、Rails の Controller 内にschema定義を書いて
Swagger v2 shema を生成するものはあるが、v2だし
※2022年3月現在では最新は OpenAPI Specification - Version 3.0.3
コードも3年ほどメンテされてないので全然ダメ

Code First Development 的なアプローチ としては

• unasuke / openapi3_definition_generator-rails
  • https://github.com/unasuke/openapi3_definition_generator-rails
  • routes.rb から OpenAPI v3 shema を生成
• k0kubun / rspec-openapi
  • https://github.com/k0kubun/rspec-openapi
  • request spec から OpenAPI v3 shema を生成

とはいえ、
unasuke / openapi3_definition_generator-rails は routes.rb から生成する特性上
当然 Request Payload や Response の定義は生成できないし
k0kubun / rspec-openapi は spec 主導であることから
committee-rails の assert_response_schema_confirm を使った spec の検証簡易化などの恩恵を受けられない。

Ruby on Rails のコードを主導で OpenAPI 定義を生み出すと
当然 Ruby on Rails 側のコードは自分たちで書いていく必要があるし、
OpenAPI Schema主導で定義を書いてからコードを書くなら
Schema First Development の恩恵を受けられるが
コードを書く前に Schema 定義を用意しないといけないという当たり前の話

sorbet-rails から自動生成できそうなもんだけど、
Request Payload はともかく Response json を型定義しないのでそのアプローチも難しそう

ということで Schema First Development の方が筋はよさそう。
とはいえVSCode拡張機能とか色んなサポートツールはあるにしろ
直接 yml を書くのは色々と厳しいので Stoplight Studio とか使って書くのがいいんじゃないかなあ

Stoplight Studio もファイル分割には完全対応してないみたいなので
Schema ごとにファイルを分割するような書き方をしたいなら yml を直接書くことになりそう

Stoplight Studio
https://stoplight.io/studio/

よほど複雑な relationship のあるテーブル構造でなければ
GET だけでも GraphQL 化する方が、より筋はよさそうだが今回はここについて突っ込んで書かない

結論

• Code First Development 的なアプローチ は Rails + OpenAPI では厳しい
  • ASP.NET Core (C#)で使える Swashbuckle はアタリマエじゃなかった
• Schema First Development 的なアプローチの方が筋がよさそう
  • Google検索すると yml を書いて Code Generation する知見が多いのも納得
  • ただし yml を直接書き続けるのは Sustainable ではないと思う
    • Stoplight Studio を使ったりするのがいいんじゃないだろうか
    • いい感じの VSCode 拡張機能があれば教えてください（他力本願寺）
  • yml で Schema 用意→ committee + committee-rails + RSpec な構成が安定しそう
• GET だけでも GraphQL 化する構成は今後 Rails の世界でも増えてくるんじゃないだろうか
  • しらんけど

あと検索してると Grape + Swagger って話もまだ結構出てくるけど
Grape は Rails API mode が出てくる前に使われてたものなので無視して良さげ