openapi-ruby 4.0.1 → 4.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1104f4d110622c6c94bce175fbb538fa07a5621ecc1d45901eac1d4f5ad1907
-  data.tar.gz: e62100c294bd83d9ddfb8f435bd92af9df3ddfce68fbb0d1e194badb5b799f5a
+  metadata.gz: f4bf806084ec440728b07b1cb5105c2e2f8529852b143a087bb919111afd6498
+  data.tar.gz: d73357f612fa69222d354a2f122a496c63bf8d8259ddb15bdfb38c898c7fb335
 SHA512:
-  metadata.gz: e04da5e753006dc5342abadf092ac9067ba46b661098eafcf090f9e64a861b6d73a46001ca3b69a21052dd6953cba2beed9fb44238dc186c465ec7fc1ceb1715
-  data.tar.gz: 63bc2eeff43bbd5efbb82c66eb00239797b7f413ada695cd1b1afe1753872d9237bf419a735fcf48cd785f2c2c58074da5a289ae8761c73df382b7d9a11871b6
+  metadata.gz: ea9f2ab82f0cdae01a6a578daa13f7274914a77b2476ba4ff7bbaf4cfd991ea685c608dcd71eac23bb2bc9ebf0ce35d0ac764b63a89bbb35add7e95c73a9d048
+  data.tar.gz: b940f94f696df915e90eccc593ae3901b1bc63229b4158391da62ffddb7fef1932a788358c1bffe771054f3e7d5f68faae36ff549ebb2c1166c078ed8ee58c66

data/README.md

@@ -469,13 +469,49 @@ 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`, `FRAMEWORK=minitest`, or `FRAMEWORK=hybrid`. Custom patterns: `PATTERN="packs/*/spec/**/*_spec.rb"`.
 
+Loading a test file normally *is* enough to run it: `rails/test_help` requires `active_support/testing/autorun`, and `rspec/autorun` does the equivalent — both register an `at_exit` hook that runs the suite. The generated script therefore installs `OpenapiRuby::Generator::AutorunSuppressor` before requiring anything of yours, so the hook is never registered. Generation stays a load-only operation no matter how your helpers are wired.
+
 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.
 
+### No database required
+
+The document is built from your declarations, never from the database — but `rails/test_help` verifies the test schema at require time (`maintain_test_schema!`), and many hand-written helpers add `ActiveRecord::Migration.check_all_pending!`. Both open a connection, which would make a database a hard requirement for generating a document that doesn't need one.
+
+Generation stubs both out, so `rake openapi_ruby:generate` runs with no database available. Nothing else about your helper changes, and the stubs exist only inside the generation subprocess — normal test runs still verify the schema as usual.
+
+Only the schema *check* is skipped. A connection is still available if your declarations genuinely need one (an enum built from a query at load time, say); such a suite needs a database either way.
+
+### Making generation cheaper (optional)
+
+Generation only needs your `path` / `api_path` declarations to register. Booting the full test framework and loading fixtures is dead weight, and on a large suite it dominates the runtime.
+
+Guard that setup with `OpenapiRuby.schema_generating?`, which returns `true` only in the rake task's subprocess (it sets `OPENAPI_RUBY_GENERATING=true`):
+
+```ruby
+# test/test_helper.rb
+require "minitest/rails" # keep the spec DSL if your api_path classes use describe/it/let
+
+return if OpenapiRuby.schema_generating?
+
+require "rails/test_help"
+# ...other test-time setup...
+```
+
+This is purely an optimization — generation is already correct and database-free without it.
+
+One caveat if you do guard: skipping `rails/test_help` also means `fixtures` is undefined, so any test file calling `fixtures :all` in its class body fails to *load*. Point `PATTERN` at just the files carrying `api_path` declarations:
+
+```bash
+PATTERN="test/integration/api/**/*_test.rb" rake openapi_ruby:generate
+```
+
+Suites using FactoryBot rather than fixtures don't hit this.
+
 ### 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:
+Here the guards described above stop being optional: without them both test frameworks wire themselves into Rails' lazy-load hooks in the same process.
 
 ```ruby
 # test/test_helper.rb
@@ -495,7 +531,7 @@ 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.
+Once the migration completes and only one test framework remains, the rake task auto-detects that framework. The guard is then no longer *required* — but it's still worth keeping for the reasons in "Making generation cheaper" above.
 
 ## Runtime Middleware
 

data/lib/openapi_ruby/generator/autorun_suppressor.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module OpenapiRuby
+  module Generator
+    # Schema generation loads the consumer's spec/test files purely to collect
+    # their `path` / `api_path` declarations. Loading them must not also *run*
+    # them.
+    #
+    # Both frameworks install an `at_exit` hook that runs the suite as a side
+    # effect of being required, and a consumer's helper almost always pulls one
+    # in transitively — `rails/test_help` requires
+    # `active_support/testing/autorun`, which calls `Minitest.autorun`; RSpec
+    # does the same via `rspec/autorun`. Without this, `rake openapi_ruby:generate`
+    # runs the entire suite and fails whenever any unrelated test fails.
+    #
+    # Installed by the generated script *before* any consumer file is required,
+    # so the hook is never registered in the first place.
+    module AutorunSuppressor
+      module_function
+
+      def install!
+        suppress_minitest!
+        suppress_rspec!
+      end
+
+      def suppress_minitest!
+        require "minitest"
+
+        ::Minitest.singleton_class.prepend(MinitestSilencer)
+      rescue LoadError
+        # Minitest isn't in the bundle — nothing to suppress.
+      end
+
+      def suppress_rspec!
+        return unless defined?(::RSpec::Core::Runner)
+
+        ::RSpec::Core::Runner.disable_autorun!
+      end
+
+      module MinitestSilencer
+        # Swallow the `at_exit` registration. Defined as a no-op rather than
+        # setting `@@installed_at_exit` so this doesn't depend on Minitest's
+        # internals.
+        def autorun
+          nil
+        end
+
+        # Belt and braces: if something registered the hook before this module
+        # was installed, the hook still fires but finds nothing to do.
+        def run(*)
+          true
+        end
+      end
+    end
+  end
+end

data/lib/openapi_ruby/generator/rake_task_support.rb

@@ -42,9 +42,22 @@ module OpenapiRuby
         end
       end
 
+      # Prepended to every generated script, before any consumer file is
+      # required. Loading the consumer's test files must neither run them
+      # (AutorunSuppressor) nor drag in a database (TestSchemaSuppressor).
+      def suppress_autorun
+        <<~RUBY.chomp
+          require "openapi_ruby/generator/autorun_suppressor"
+          require "openapi_ruby/generator/test_schema_suppressor"
+          OpenapiRuby::Generator::AutorunSuppressor.install!
+          OpenapiRuby::Generator::TestSchemaSuppressor.install!
+        RUBY
+      end
+
       def rspec_script(pattern)
         <<~RUBY
           require "rspec/core"
+          #{suppress_autorun}
           $LOAD_PATH.unshift(File.expand_path("spec")) unless $LOAD_PATH.include?(File.expand_path("spec"))
           #{glob_loads(pattern)}
           OpenapiRuby::Generator::SchemaWriter.generate_all!
@@ -54,6 +67,7 @@ module OpenapiRuby
       def minitest_script(pattern)
         <<~RUBY
           require "openapi_ruby/minitest"
+          #{suppress_autorun}
           $LOAD_PATH.unshift(File.expand_path("test")) unless $LOAD_PATH.include?(File.expand_path("test"))
           #{glob_loads(pattern)}
           OpenapiRuby::Generator::SchemaWriter.generate_all!
@@ -86,6 +100,7 @@ module OpenapiRuby
           require "rspec/core"
           require "openapi_ruby/rspec"
           require "openapi_ruby/minitest"
+          #{suppress_autorun}
 
           load_with_path = lambda do |dir, glob|
             path = File.expand_path(dir)

data/lib/openapi_ruby/generator/test_schema_suppressor.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module OpenapiRuby
+  module Generator
+    # Schema generation never runs tests, so keeping the test database's schema
+    # current is wasted work — but `rails/test_help` does it unconditionally at
+    # require time (`rails/testing/maintain_test_schema` → `maintain_test_schema!`),
+    # which opens a database connection. That makes a database a hard
+    # requirement for generating a document that doesn't depend on one.
+    #
+    # `maintain_test_schema!` is a no-op when the setting is off, so turning it
+    # off for the generation subprocess drops the requirement.
+    #
+    # This only skips the schema *check*. A connection is still available if the
+    # consumer's declarations genuinely need one (say, an enum built from a
+    # query at load time) — such a suite needs a database either way.
+    module TestSchemaSuppressor
+      module_function
+
+      def install!
+        return unless defined?(::ActiveSupport) && ::ActiveSupport.respond_to?(:on_load)
+
+        # Registered as a load hook so it applies whenever the consumer's helper
+        # boots Rails, rather than depending on require order.
+        ::ActiveSupport.on_load(:active_record) do
+          OpenapiRuby::Generator::TestSchemaSuppressor.disable!
+        end
+      end
+
+      # Neutralises the methods rather than clearing
+      # `ActiveRecord.maintain_test_schema`. The flag is reapplied from app
+      # config by the `active_record.set_configs` initializer, which runs after
+      # any load hook we can register from here — so setting it is silently
+      # undone before `rails/test_help` reads it.
+      def disable!
+        ::ActiveRecord::Migration.singleton_class.prepend(MigrationSilencer)
+      end
+
+      module MigrationSilencer
+        # Called by rails/test_help at require time.
+        def maintain_test_schema!
+          nil
+        end
+
+        # Not called by Rails during boot, but a common addition to a
+        # hand-written test_helper. Same intent as the above: assert the test
+        # database matches the migrations. Nothing is loaded from the database
+        # to build the document, so there is nothing to verify.
+        def check_all_pending!
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/openapi_ruby/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openapi-ruby
 version: !ruby/object:Gem::Version
-  version: 4.0.1
+  version: 4.0.3
 platform: ruby
 authors:
 - Morten Hartvig
@@ -105,8 +105,10 @@ files:
 - lib/openapi_ruby/dsl/response_context.rb
 - lib/openapi_ruby/engine.rb
 - lib/openapi_ruby/errors.rb
+- lib/openapi_ruby/generator/autorun_suppressor.rb
 - lib/openapi_ruby/generator/rake_task_support.rb
 - lib/openapi_ruby/generator/schema_writer.rb
+- lib/openapi_ruby/generator/test_schema_suppressor.rb
 - lib/openapi_ruby/middleware/coercion.rb
 - lib/openapi_ruby/middleware/error_handler.rb
 - lib/openapi_ruby/middleware/path_matcher.rb