openapi-ruby 3.3.0 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2596878f73873970637c965935c1f4689cc744f3496467d734bd9a2c816904ee
-  data.tar.gz: 2c7f2d7b4497175d0c558f2179888529ae1397d724cba0088248049ef5fda518
+  metadata.gz: 4fd91990e73c6bcd5fae00558bb63afd1c4999de976b16d542aa495ddf2ad6a4
+  data.tar.gz: 19391cec8179b314284b51afa6adc977849f75aa431a7ec54df70f29b9877e45
 SHA512:
-  metadata.gz: d54c13cb1de806e0e5f21ed1e17d6287a525b00be8654d2c77e554a6bc6762dc206002797874fa6882872754b2bc6438dbfa590e0f3c03f0211383d1fa2490ff
-  data.tar.gz: fb01ab7bb2b8f51d7fb9ef0432a261717d5cf1dc90a7c2c17168f3039456d0b5af99c74eb1853d9ebbf1df80dc8410bbaffa5c53af4f3799960a00c4a128d287
+  metadata.gz: e9384c41d176a5cdf12a8164a148e8ff0a853aa15c73b06efb4f32bc96d40aaa18d4667c93ab6db863bf12de8eac783308a232a99dad66f755b3e1141ad456e5
+  data.tar.gz: c6d8b92d8473ac2f2582632c93d1f5d72fc41645b3c34a0b88192530d0bd1808aef836ac99b8864a92a88cb0587a89f1b0cf867811190e2758fdb86900e25552

data/README.md

@@ -469,10 +469,36 @@ Generate OpenAPI spec files without running tests:
 rake openapi_ruby:generate
 ```
 
-This loads spec/test files to collect API definitions and writes schemas without running any tests. It auto-detects the test framework, or you can set `FRAMEWORK=rspec` or `FRAMEWORK=minitest`. Custom patterns: `PATTERN="packs/*/spec/**/*_spec.rb"`.
+This loads spec/test files to collect API definitions and writes schemas without running any tests. It auto-detects the test framework, or you can set `FRAMEWORK=rspec`, `FRAMEWORK=minitest`, or `FRAMEWORK=hybrid`. Custom patterns: `PATTERN="packs/*/spec/**/*_spec.rb"`.
 
 Schemas are **only** written by the rake task — running tests (`bundle exec rspec`, `rails test`) does not generate or overwrite schema files. This prevents partial schema overwrites when running a subset of specs.
 
+### Migrating from RSpec to Minitest (or vice versa)
+
+When both `spec/spec_helper.rb` and `test/test_helper.rb` are present, the rake task auto-selects `FRAMEWORK=hybrid` — it requires both adapters and loads both glob patterns (`spec/**/*_spec.rb,test/**/*_test.rb`) into one process. Style 1 `path(...)` and Style 2 `api_path(...)` definitions register into the same `MetadataStore`, so a single schema file holds paths contributed by either DSL.
+
+Two things to set up on the consumer side so the two test frameworks don't both wire themselves into Rails' lazy-load hooks during schema generation:
+
+```ruby
+# test/test_helper.rb
+unless OpenapiRuby.schema_generating?
+  require "rails/test_help"
+  # ...other test-time setup...
+end
+```
+
+```ruby
+# spec/rails_helper.rb
+unless OpenapiRuby.schema_generating?
+  require "rspec/rails"
+  # ...other spec-time setup...
+end
+```
+
+`OpenapiRuby.schema_generating?` returns `true` when the rake task launched the current process (it sets `OPENAPI_RUBY_GENERATING=true` in the subprocess). With the guards in place, neither test framework boots its full Rails integration during generation — only the DSL needs to be live for `api_path` / `path` to register.
+
+The guards are only needed while both frameworks are live. Once the migration completes and only one test framework remains, the rake task auto-detects that framework and the guard becomes dead code that can be removed.
+
 ## Runtime Middleware
 
 Validate requests and responses against your OpenAPI spec at runtime:

data/lib/openapi_ruby/generator/rake_task_support.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module OpenapiRuby
+  module Generator
+    # Helpers backing the `openapi_ruby:generate` rake task. Extracted
+    # so the framework detection / script generation logic is testable
+    # without booting Rake.
+    module RakeTaskSupport
+      module_function
+
+      def detect_test_framework
+        rspec = File.exist?("spec/spec_helper.rb") || File.exist?("spec/rails_helper.rb")
+        minitest = File.exist?("test/test_helper.rb")
+
+        if rspec && minitest
+          "hybrid"
+        elsif rspec
+          "rspec"
+        elsif minitest
+          "minitest"
+        else
+          raise ArgumentError,
+            "Could not detect test framework. Set FRAMEWORK=rspec, FRAMEWORK=minitest, or FRAMEWORK=hybrid."
+        end
+      end
+
+      def default_pattern_for(framework)
+        case framework
+        when "rspec" then "spec/**/*_spec.rb"
+        when "minitest" then "test/**/*_test.rb"
+        when "hybrid" then "spec/**/*_spec.rb,test/**/*_test.rb"
+        end
+      end
+
+      def generate_script(framework, pattern)
+        case framework
+        when "rspec" then rspec_script(pattern)
+        when "minitest" then minitest_script(pattern)
+        when "hybrid" then hybrid_script(pattern)
+        else
+          raise ArgumentError, "Unknown test framework '#{framework}'."
+        end
+      end
+
+      def rspec_script(pattern)
+        <<~RUBY
+          require "rspec/core"
+          $LOAD_PATH.unshift(File.expand_path("spec")) unless $LOAD_PATH.include?(File.expand_path("spec"))
+          #{glob_loads(pattern)}
+          OpenapiRuby::Generator::SchemaWriter.generate_all!
+        RUBY
+      end
+
+      def minitest_script(pattern)
+        <<~RUBY
+          require "openapi_ruby/minitest"
+          #{glob_loads(pattern)}
+          OpenapiRuby::Generator::SchemaWriter.generate_all!
+        RUBY
+      end
+
+      # Loads both adapters and both file globs in one process. Useful
+      # during a phased RSpec → Minitest migration where the suite
+      # holds both DSL styles. Consumers should guard
+      # `require "rails/test_help"` and `require "rspec/rails"` in
+      # their test helpers with `unless OpenapiRuby.schema_generating?`
+      # so the two test frameworks don't both register Rails lazy
+      # hooks in the same process — only the DSL needs to be live for
+      # schema generation.
+      def hybrid_script(pattern)
+        <<~RUBY
+          require "rspec/core"
+          require "openapi_ruby/rspec"
+          require "openapi_ruby/minitest"
+          $LOAD_PATH.unshift(File.expand_path("spec")) unless $LOAD_PATH.include?(File.expand_path("spec"))
+          $LOAD_PATH.unshift(File.expand_path("test")) unless $LOAD_PATH.include?(File.expand_path("test"))
+          #{glob_loads(pattern)}
+          OpenapiRuby::Generator::SchemaWriter.generate_all!
+        RUBY
+      end
+
+      def glob_loads(pattern)
+        pattern.split(",").map do |p|
+          %[Dir.glob(#{p.strip.inspect}).sort.each { |f| require File.expand_path(f) }]
+        end.join("\n")
+      end
+    end
+  end
+end

data/lib/openapi_ruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenapiRuby
-  VERSION = "3.3.0"
+  VERSION = "3.5.0"
 end

data/lib/openapi_ruby.rb

@@ -27,6 +27,22 @@ module OpenapiRuby
     def reset_configuration!
       @configuration = Configuration.new
     end
+
+    # True when the current process was started by `openapi_ruby:generate`
+    # (the rake task sets OPENAPI_RUBY_GENERATING=true in the subprocess).
+    #
+    # Useful in consumer test helpers to guard test-framework requires
+    # that conflict when both `rspec/rails` and `rails/test_help` load
+    # in the same process (the FRAMEWORK=hybrid case):
+    #
+    #   # test/test_helper.rb
+    #   unless OpenapiRuby.schema_generating?
+    #     require "rails/test_help"
+    #     # ...other test-time setup...
+    #   end
+    def schema_generating?
+      ENV["OPENAPI_RUBY_GENERATING"] == "true"
+    end
   end
 end
 
@@ -47,6 +63,7 @@ require_relative "openapi_ruby/testing/request_validator"
 require_relative "openapi_ruby/testing/assertions"
 require_relative "openapi_ruby/testing/coverage"
 require_relative "openapi_ruby/generator/schema_writer"
+require_relative "openapi_ruby/generator/rake_task_support"
 require_relative "openapi_ruby/middleware/path_matcher"
 require_relative "openapi_ruby/middleware/coercion"
 require_relative "openapi_ruby/middleware/error_handler"

data/lib/tasks/openapi_ruby.rake

@@ -1,55 +1,21 @@
 # frozen_string_literal: true
 
+require "openapi_ruby/generator/rake_task_support"
+
 namespace :openapi_ruby do
   desc "Generate OpenAPI schema files from spec definitions and components"
   task :generate do
-    framework = ENV.fetch("FRAMEWORK", detect_test_framework).to_s
-    pattern = ENV.fetch("PATTERN", default_pattern_for(framework))
+    support = OpenapiRuby::Generator::RakeTaskSupport
+    framework = ENV.fetch("FRAMEWORK") { support.detect_test_framework }.to_s
+    pattern = ENV.fetch("PATTERN") { support.default_pattern_for(framework) }
 
     # Spawn a subprocess so RAILS_ENV defaults to "test" cleanly,
     # just like rswag did with RSpec::Core::RakeTask.
     env = {"RAILS_ENV" => ENV.fetch("RAILS_ENV", "test"), "OPENAPI_RUBY_GENERATING" => "true"}
-    script = generate_script(framework, pattern)
+    script = support.generate_script(framework, pattern)
     command = "bundle exec ruby -e #{Shellwords.escape(script)}"
 
     puts "Generating OpenAPI schemas (#{framework})..."
     system(env, command) || abort("Schema generation failed")
   end
 end
-
-def detect_test_framework
-  if File.exist?("spec/spec_helper.rb") || File.exist?("spec/rails_helper.rb")
-    "rspec"
-  elsif File.exist?("test/test_helper.rb")
-    "minitest"
-  else
-    abort "Could not detect test framework. Set FRAMEWORK=rspec or FRAMEWORK=minitest."
-  end
-end
-
-def default_pattern_for(framework)
-  case framework
-  when "rspec" then "spec/**/*_spec.rb"
-  when "minitest" then "test/**/*_test.rb"
-  end
-end
-
-def generate_script(framework, pattern)
-  case framework
-  when "rspec"
-    <<~RUBY
-      require "rspec/core"
-      $LOAD_PATH.unshift(File.expand_path("spec")) unless $LOAD_PATH.include?(File.expand_path("spec"))
-      #{pattern.split(",").map { |p| %[Dir.glob(#{p.strip.inspect}).sort.each { |f| require File.expand_path(f) }] }.join("\n")}
-      OpenapiRuby::Generator::SchemaWriter.generate_all!
-    RUBY
-  when "minitest"
-    <<~RUBY
-      require "openapi_ruby/minitest"
-      #{pattern.split(",").map { |p| %[Dir.glob(#{p.strip.inspect}).sort.each { |f| require File.expand_path(f) }] }.join("\n")}
-      OpenapiRuby::Generator::SchemaWriter.generate_all!
-    RUBY
-  else
-    abort "Unknown test framework '#{framework}'."
-  end
-end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openapi-ruby
 version: !ruby/object:Gem::Version
-  version: 3.3.0
+  version: 3.5.0
 platform: ruby
 authors:
 - Morten Hartvig
@@ -105,6 +105,7 @@ files:
 - lib/openapi_ruby/dsl/response_context.rb
 - lib/openapi_ruby/engine.rb
 - lib/openapi_ruby/errors.rb
+- lib/openapi_ruby/generator/rake_task_support.rb
 - lib/openapi_ruby/generator/schema_writer.rb
 - lib/openapi_ruby/middleware/coercion.rb
 - lib/openapi_ruby/middleware/error_handler.rb