Skip to content

Support Ruby 3.3, 3.4, 4.0 and Rails 8.1, and fix rake api_spec on Rails 7.0+ - #20

Merged
stomk merged 7 commits into
masterfrom
chore/support-ruby-4-0-rails-8-1
Nov 13, 2026
Merged

stomk merged 7 commits into
masterfrom
chore/support-ruby-4-0-rails-8-1

Conversation

@snhrm

@snhrm snhrm commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

Why

  • アプリを Ruby 3.4 / 4.0、Rails 8.1 に上げられるようにするため。現在の 0.6.1 は actionpack / railties < 7.2 になっている
  • rake api_spec が Rails 7.0 以降、type メソッドが無いという NoMethodError で失敗する。rake の中では routes が eager_load されない (config.rake_eager_load が既定で false) ので、ActionDispatch::Journey::Ast に対して type を呼んでいる。eager_load した状態では nil に対して呼ぶ
  • wantedly で rake api_spec を実行して見つかった、既存のバグ 2 つ
    • serializer: を指定した belongs_to の $ref が、#/components/schemas/["OpenUser"] のように配列を文字列にしたものになる
    • has_many の type: に配列ではなくクラスなどを書いた serializer が 1 つでもあると、rake api_spec が止まるか、不正な $ref を出力する。ActiveRecord のモデルを書いた場合、テーブルが空なら TypeError: no implicit conversion of nil into Hash で止まる

What

  • RoutesFinder が route.path.ast ではなく route.path.spec を使うように直す
    • Rails 7.0 以降の Pattern#ast は Journey::Ast というラッパーを返し、eager_load! の後は nil になる
    • Pattern#spec は Rails 5.0〜8.1 のどの版でも、生のノードツリーを返す
  • Rails が実際に描いた RouteSet を使う spec を、routes を eager_load しない場合とする場合の両方について追加する。既存の spec は Rails を全部 mock しているので、この不具合を検出できなかった
  • open_api_belongs_to_associations で、serializer: を指定したときの型を配列で包まないようにする
    • 最初の実装では has_one も同じように配列で包んでいた。7436451 (2018-12) で has_one だけが直り、belongs_to が残っていた
    • has_many / has_one / belongs_to の型を確かめる spec を追加した。serializer: だけ、type: だけ、両方 (serializer: が優先される) の 3 通りを見る
  • ComponentsBuilder で、has_many の型が配列でないか空の配列のときは、警告を出してその関連だけを飛ばす
    • これまでは each の中の return でメソッド全体が nil を返し、merge!(nil) で TypeError になっていた
    • first は型が配列のときだけ呼ぶようにした。ActiveRecord のモデルだと first が DB クエリを実行し、データがあればレコードが返って不正な $ref が出力されるため。文字列 ("Author") でも ActiveSupport の String#first で "A" が返っていた
  • actionpack / railties の上限を < 8.2 にし、open_api >= 0.6.3 を必須にする
    • open_api 0.6.3 には、forwardable を明示的に require する修正 (Support Ruby 3.3, 3.4, 4.0 and Rails 8.1 open_api#18) も入っている
    • この修正が無いと、Ruby 3.3 以降では Rails アプリの外で require "open_api_annotator" したときに NameError: uninitialized constant OpenApi::Paths::Forwardable になる。open_api_annotator が require "rails" の直後に require "open_api" するため
    • Rails アプリの中では action_controller が先に forwardable を読み込むので、表に出ていなかった。この gem の spec でも、spec_helper が先に読む simplecov が forwardable を読み込むので検出できていなかった
  • 開発依存の bundler ~> 2.0 を削除し、CI を Ruby 3.3 / 3.4 / 4.0 と Rails 7.0〜8.1 にし、Code Climate を削除する。どれも Support Ruby 3.3, 3.4, 4.0 and Rails 8.1 open_api#18 と同じ内容
  • 0.6.2 に上げ、CHANGELOG を追記する

確認したこと

  • spec が全件通る (25 examples, 0 failures)
    • 対象は、Ruby 3.3 / 3.4 / 4.0 × Rails 7.0〜8.1
    • open_api は rubygems で公開された 0.6.3 を使った
  • 追加した RoutesFinder の spec は、.ast / .ast.root に戻す変異、ast があればそちらを使う変異 (route.path.try(:ast) || route.path.spec)、パラメータを落とす変異で落ちる
  • 既存バグの修正の spec は、次の変異でそれぞれ落ちる (Ruby 3.3 / 4.0)
    • belongs_to の型を配列で包む / has_one の型を配列で包む / has_many の型の [...] を外す
    • type: を指定したときの型を使わない / type: の型を配列で包む / serializer: より type: を優先する (has_many / has_one / belongs_to のそれぞれ)
    • next を return に戻す
    • 配列かどうかの判定を外す / クラスかどうかの判定に変える
    • 警告を外す / 警告文から型を外す
    • スキップ処理ごと外す
  • Ruby 3.3 / 4.0 で、open_api 0.6.3 なら require "open_api_annotator" が通り、修正前の open_api では NameError になる
  • RoutesFinder の修正について、ダミーの Rails アプリで rake api_spec を実行した (既存バグの修正の確認は下の「wantedly での確認」)
    • 対象は、Rails 7.0〜8.1 × Ruby 3.3 / 3.4 / 4.0、eager_load の有無の両方
    • 生成された YAML は、Rails 6.1 で修正前のコードが出したものと一致した

wantedly での確認

wantedly master のコピーに wantedly/open_api#18 とこの PR の gem を入れ、development 環境で rake api_spec:create を実行した。

  • wantedly/wantedly#81643 (CandidacySerializer の has_many :selection_invitation_logs の type: を配列にする 1 行。wantedly/wantedly#73734 (2025-05-20) からクラスになっていた) を当てた場合
    • exit 0 (paths 139 / schemas 122)
    • コミット済みの swagger/api_v2.yml と比べて、既存の path と、既存 schema の既存プロパティは、Api::ProjectRecommendation の supporter の $ref が #/components/schemas/OpenUser に直ったこと以外は一致した
    • それ以外の差分は、2025-05 以降に追加された path 10 本・schema 7 個・既存 schema へのプロパティ 15 個と、wantedly/wantedly#81500 で消し残っていた AttachmentFile schema の削除だけ
  • wantedly/wantedly#81643 を当てない場合
    • exit 0 で通るが、Skipped CandidacySerializer#selection_invitation_logs: ... の警告が出て、Candidacy の selection_invitation_logs だけが出力から抜ける
    • 正しい定義を出すには、wantedly/wantedly#81643 が必要

merge の順番

  1. Support Ruby 3.3, 3.4, 4.0 and Rails 8.1 open_api#18 を merge して、0.6.3 をリリースする (2026-11-12 に完了)
  2. この PR の CI を再実行する (完了。全セル pass)
  3. merge して bundle exec rake release を実行する
  4. wantedly で両方の gem を上げ、wantedly/wantedly#81643 が入った状態で rake api_spec:create を実行して swagger/api_v2.yml を再生成する
    • gem は bundle update --conservative open_api_annotator open_api で上げる。--conservative を付けないと、actionpack / railties など、両 gem が依存している gem も更新の対象になる

snhrm added 4 commits October 29, 2026 23:22
Since Rails 7.0, Journey::Path::Pattern#ast returns a Journey::Ast wrapper
(and is cleared on eager_load!), so PathResolver failed on ast.type.
Pattern#spec returns the raw node tree on every Rails version.
- Relax actionpack / railties upper bound to < 8.2
- Require open_api >= 0.6.3, the first version allowing activesupport 7.2+
- Drop bundler ~> 2.0 dev dependency, which conflicts with Bundler 4 bundled with Ruby 4.0
- Test Ruby 3.3, 3.4, 4.0 and Rails 7.0 to 8.1 on CI
- Remove Code Climate coverage upload, whose API was shut down
Comment on lines +16 to 17
- ruby: "3.3"
gemfile: "gemfiles/rails-7.0.gemfile"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wantedly/open_api#18 では 7ad9e95 で Ruby 4.0 × rails-7.0 のセルを追加していますが、こちらには入っていないようです。
annotator は railties / actionpack も読み込むので、対応表の中では Ruby 4.0 × Rails 7.0 がいちばん壊れやすい組み合わせだと思います (手元では spec は通りますが、Rails 7.0 から tsort の deprecation warning が出ます)。open_api#18 に揃えて追加しておくのはどうでしょう。

Suggested change
- ruby: "3.3"
gemfile: "gemfiles/rails-7.0.gemfile"
- ruby: "3.3"
gemfile: "gemfiles/rails-7.0.gemfile"
- ruby: "4.0"
gemfile: "gemfiles/rails-7.0.gemfile"

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ありがとうございます、open_api#18 に揃えて Ruby 4.0 × rails-7.0 のセルを追加しました (c1abd20)。
手元 (Docker) でも Ruby 4.0.9 × railties 7.0.10 で 13 examples, 0 failures を確認しています。tsort の warning は railties 7.0 の rails/initializable.rb 由来で 7.1 以降では出ないため、今回はそのままにしています。
なお open_api 0.6.3 の公開前なので、このセルも他と同様に依存解決で落ちる状態です。

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ご対応ありがとうございます、c1abd20 を確認しました。LGTM です。
open_api#18 の merge と 0.6.3 のリリース後に、こちらの CI を再実行して通ったことを確認してから approve します。

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

追加の 664f4e8 (belongs_to の $ref の修正と、配列でない has_many のスキップ) も確認しました。こちらも LGTM です。
approve は前回書いたとおり、open_api 0.6.3 のリリース後に CI が通ったことを確認してから行います。

@snhrm

snhrm commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

wantedly で動作確認したところ、この PR だけでは wantedly の rake api_spec:create が最後まで通らないことが分かったので、本文に「wantedly で rake api_spec を通すには、wantedly 側の修正も必要」の節を追記しました。

  • この PR で path の生成は通るようになりますが、schema の生成で TypeError: no implicit conversion of nil into Hash になります
  • 原因は wantedly の CandidacySerializer の has_many :selection_invitation_logs, type: SelectionInvitationLog (配列ではなくクラス) で、wantedly/wantedly#73734 (2025-05-20) から壊れていました
  • wantedly 側の修正は wantedly/wantedly#81643 です (1 行、API のレスポンスは変わりません)
  • #81643 も当てた wantedly master のコピーでは rake api_spec:create が exit 0 で通り、既存の path / schema の出力はコミット済みの swagger/api_v2.yml と一致しました

この PR の変更内容自体は変わっていません。

… type

- open_api_belongs_to_associations wrapped the serializer's resource name
  in an array, producing $ref like #/components/schemas/["OpenUser"].
- build_has_many_association_properties called first on the annotated
  type even when it was not an array (e.g. an ActiveRecord model, which
  runs a query), and returned nil from the whole method when it got nil,
  making rake api_spec raise TypeError. Now it calls first only on arrays
  and skips the association with a warning otherwise.
@snhrm

snhrm commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

LGTM いただいた後ですが、wantedly で rake api_spec を動かして見つかった既存バグ 2 件の修正を、この PR に追加しました (664f4e8)。

  • serializer: を指定した belongs_to の $ref が #/components/schemas/["OpenUser"] になっていたのを直しました
  • has_many の type: が配列でない場合 (wantedly の CandidacySerializer のように) に rake api_spec が TypeError で止まっていたので、警告を出してその関連だけを飛ばすようにしました

詳細は本文の What と「wantedly での確認」に追記しています。お手数ですが、差分 (lib 2 ファイルと spec) の確認をお願いします。

…type:

- Run the RoutesFinder spec on routes both before and after eager_load!.
  rake tasks do not eager load routes by default, so Pattern#ast is still
  a Journey::Ast there.
- Test has_many, has_one and belongs_to annotated with serializer:, type:
  and both.
@snhrm

snhrm commented Nov 12, 2026

Copy link
Copy Markdown
Contributor Author

open_api 0.6.3 がリリースされたので、この PR の CI を再実行し、全セル pass しました。

あわせて最終確認をしたところ、追加した spec に穴があったので、spec だけを追加しました (640f1db。lib の変更はありません)。この commit でも CI は全セル pass しています。

  • RoutesFinder: eager_load! した後の状態しか見ていなかったので、eager_load しない状態も見るようにしました
    • rake の中では routes が eager_load されない (config.rake_eager_load が既定で false) ので、rake api_spec で実際に使われるのはこちらの状態です
    • これまでは、route.path.try(:ast) || route.path.spec のような変更を入れても spec が通り、今回の NoMethodError が再発しても検出できませんでした
  • SerializerAnnotatable: serializer: を指定した場合しか見ていなかったので、type: だけを指定した場合と、両方を指定した場合 (serializer: が優先される) も見るようにしました
    • これまでは、type: を使う分岐を消しても、type: を優先するように変えても spec が通っていました
    • wantedly では、type: だけを指定した関連が belongs_to で 16 か所、has_one で 33 か所あり、両方を指定した関連が has_one で 10 か所、has_many で 3 か所あります

本文も、Why のエラーの説明、What の belongs_to の修正の経緯と追加した spec の説明、「確認したこと」、「merge の順番」を更新しています。お手数ですが、差分 (spec 2 ファイル) の確認をお願いします。

@snhrm
snhrm marked this pull request as ready for review November 13, 2026 02:29

@madapaja madapaja left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

640f1db (spec のみ) を確認しました。eager_load しない場合の RoutesFinder の spec が route.path.try(:ast) || route.path.spec で落ちること、type: / serializer: の spec が「type: を無視」「type: を優先」で落ちることも手元 (Ruby 3.4) で確かめました。
open_api 0.6.3 のリリース後に CI が全セル通っているので approve します。

@snhrm

snhrm commented Nov 13, 2026

Copy link
Copy Markdown
Contributor Author

wantedly での確認 (640f1db)

wantedly の最新の master (ecda73b9407。wantedly/wantedly#81643 は merge 済み) に、公開された open_api 0.6.3 とこの PR の 640f1db を入れ、ローカル (Docker) の development 環境で rake api_spec:create を実行しました。問題なく通っています。

  • gem は、本文に書いた bundle update --conservative open_api_annotator open_api で上げた
    • Gemfile.lock で変わったのは、open_api (0.6.2 → 0.6.3) と open_api_annotator (0.6.1 → 0.6.2) だけ。Rails は 7.1.6 のまま
    • --conservative を付けないと、rack / nokogiri / prism などのほかの gem も変わった
  • rake api_spec:create は exit 0 (paths 139 / schemas 122)
  • この PR のバグ修正による出力の変化は、Api::ProjectRecommendation の supporter の $ref が #/components/schemas/["OpenUser"] から #/components/schemas/OpenUser に直った 1 行だけだった (バグ修正前の c1abd20 と比べた)
  • wantedly/wantedly#81643 を戻した場合も exit 0 で通る。Skipped CandidacySerializer#selection_invitation_logs: ... の警告が出て、Candidacy の selection_invitation_logs だけが出力から抜ける
  • コミット済みの swagger/api_v2.yml との差分は、本文の「wantedly での確認」に書いたものと同じだった

@snhrm
snhrm requested a review from stomk November 13, 2026 05:28
@stomk
stomk merged commit 7c03d27 into master Nov 13, 2026
16 checks passed
@stomk

stomk commented Nov 13, 2026

Copy link
Copy Markdown
Member

新しいバージョンリリースしました
https://rubygems.org/gems/open_api_annotator

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants