openapi-ruby 4.0.2 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27487aa88423921e2f0274f7d93a5abd534dc3fca2567692d07c73001b66017f
-  data.tar.gz: 3f62cffd0f03d943b7198e6d230b5ad851746d4e7982f65ea891d213fd509490
+  metadata.gz: 7990b0f6b4af407b5df408029221d095428b91e0f0cc71f798f77e6d37901eb5
+  data.tar.gz: 4514fb71405d81e25a2e079e9e0ebcb03110f1430c327be386fd4d63c336eff1
 SHA512:
-  metadata.gz: 580fb57048ffea5a623ba2b7940b83c8bee9a8e7d73db91ccbe566095fcf64b09ae0228fe9a791df6c2a7a9c03f6a14cdb92d65a24cfd7b881bc245715f1e198
-  data.tar.gz: be207593a6158ea4b1fd0cc0758d332f5557ba61788b04a32e8eabbc85ae8300060956d20bfad9198952bccd92e0ce41e76fd2a02e298cf4dff17a8a0ec2cd10
+  metadata.gz: 6f2f27ba8f415683fb454b707e90eec7b9bb3f6adf5c5c1835b1f4002d83afb898414d4a735cc372d9b6a5a47f636c7aa2d0bf24dee092c5fe2b40180828a218
+  data.tar.gz: 666bb48fd0aaa60c3b25ab242e180735513416db9b34aaa22ec9dcabd54cc0dbcb2aeb5a50d36c7ae860f68fda83cb5261e0706561decce219f657fde4003853

data/README.md

@@ -473,9 +473,17 @@ Loading a test file normally *is* enough to run it: `rails/test_help` requires `
 
 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. Everything else a test helper does — connecting to a database, loading fixtures, `maintain_test_schema!` — is dead weight, and on a large suite it dominates the runtime.
+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`):
 
@@ -489,7 +497,7 @@ require "rails/test_help"
 # ...other test-time setup...
 ```
 
-This is an optimization, not a correctness requirement — the suppressor handles the autorun hook either way.
+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:
 
@@ -499,6 +507,65 @@ PATTERN="test/integration/api/**/*_test.rb" rake openapi_ruby:generate
 
 Suites using FactoryBot rather than fixtures don't hit this.
 
+### How a request finds its api_path (Style 2)
+
+Style 2 separates the `api_path` declaration from the request that exercises
+it, so `assert_api_response` has to match the request back to a declaration. It
+narrows the declared paths by, in order:
+
+1. the verb — only paths declaring it stay in
+2. the path params — a path needing `{project_id}` is out if none was supplied,
+   and a path is out if it doesn't use every key given in `path_params:`
+3. the expected status — `assert_api_response :put, 422` skips paths that don't
+   declare a 422 for that verb
+4. how many supplied keys the path can explain, as either one of its own path
+   params or a parameter declared on the operation
+
+That resolves a collection path against a member path, nested resources, and
+sibling paths distinguished by status. It cannot resolve paths that agree on all
+four:
+
+```ruby
+api_path "/timers/{id}"       { put("Update") { response(200, "ok") } }
+api_path "/timers/{id}/start" { put("Start")  { response(200, "ok") } }
+api_path "/timers/{id}/stop"  { put("Stop")   { response(200, "ok") } }
+```
+
+Nothing at the call site tells those apart, so that raises
+`OpenapiRuby::AmbiguousApiPath` naming the candidates rather than silently
+picking the first and validating against the wrong response schema. Two ways to
+resolve it. Name the path on the request:
+
+```ruby
+assert_api_response :put, 200, path_params: {id: timer.id}, api_path: "/timers/{id}/start"
+```
+
+Or, in RSpec, declare each path in its own example group — a nested `describe`
+only sees paths declared at or above it:
+
+```ruby
+describe "start" do
+  api_path("/timers/{id}/start") { put("Start") { response(200, "ok") } }
+
+  it { assert_api_response :put, 200, path_params: {id: timer.id} }
+end
+
+describe "stop" do
+  api_path("/timers/{id}/stop") { put("Stop") { response(200, "ok") } }
+
+  it { assert_api_response :put, 200, path_params: {id: timer.id} }
+end
+```
+
+To require one path per test class regardless, switch on:
+
+```ruby
+config.single_api_path_per_class = true
+```
+
+`api_path` then raises `OpenapiRuby::MultipleApiPaths` as soon as a class
+declares a second path. Off by default.
+
 ### 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.

data/lib/openapi_ruby/adapters/context_resolution.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module OpenapiRuby
+  module Adapters
+    # Shared by the Minitest and RSpec Style 2 adapters.
+    #
+    # Style 2 separates the `api_path` declaration from the request that
+    # exercises it, so the request has to be matched back to a declaration.
+    # Everything used to do that here is a hard fact about the request, never a
+    # guess: the verb, which path params the template needs against which the
+    # caller supplied, whether the candidate declares the status the assertion
+    # demands, and whether the remaining params are declared on the operation.
+    #
+    # That leaves one case it cannot decide. `/timers/{id}` and
+    # `/timers/{id}/start` under the same verb, the same status and the same
+    # `{id}` are indistinguishable from the call site — the information simply
+    # isn't there. Picking one silently sends the request to the wrong endpoint
+    # and validates it against the wrong response schema, so a test passes while
+    # exercising something else. Raise instead, and name the candidates; the
+    # author resolves it by passing `api_path:` or by scoping the declarations.
+    module ContextResolution
+      module_function
+
+      def resolve(contexts, method, path_params, owner:, params: {}, expected_status: nil, api_path: nil)
+        if api_path
+          selected = find_declared(contexts, api_path)
+          raise OpenapiRuby::Error, unknown_path_message(contexts, api_path, owner) unless selected
+          return selected
+        end
+
+        candidates = contexts.select { |ctx| ctx.operations.key?(method.to_s) }
+        return candidates.first if candidates.size <= 1
+
+        supplied = keys_of(params) | keys_of(path_params)
+        required = keys_of(path_params)
+
+        candidates = narrow(candidates) { |ctx| path_params_fit?(ctx, required, supplied) }
+        if expected_status
+          candidates = narrow(candidates) { |ctx| declares_status?(ctx, method, expected_status) }
+        end
+        candidates = fewest_unaccounted(candidates, method, supplied)
+
+        return candidates.first if candidates.size == 1
+
+        raise OpenapiRuby::AmbiguousApiPath, ambiguity_message(candidates, method, owner)
+      end
+
+      # A template only fits if it needs no path param the caller did not supply,
+      # and uses every param the caller explicitly declared as one.
+      def path_params_fit?(context, required, supplied)
+        template = template_params(context)
+
+        (required - template).empty? && (template - supplied).empty?
+      end
+
+      def declares_status?(context, method, expected_status)
+        context.operations[method.to_s].responses.key?(expected_status.to_s)
+      end
+
+      # Prefer the candidate that can explain the most supplied keys as either a
+      # path param of its own template or a parameter declared on it. A key that
+      # fits nowhere means the request was probably meant for a sibling path.
+      def fewest_unaccounted(candidates, method, supplied)
+        ranked = candidates.group_by { |ctx| (supplied - accounted_keys(ctx, method)).size }
+
+        ranked[ranked.keys.min]
+      end
+
+      def accounted_keys(context, method)
+        declared = context.path_parameters + (context.operations[method.to_s]&.parameters || [])
+
+        template_params(context) | declared.filter_map { |param| param["name"]&.to_s }
+      end
+
+      def template_params(context)
+        context.path_template.scan(/\{(\w+)\}/).flatten
+      end
+
+      def find_declared(contexts, api_path)
+        template = api_path.respond_to?(:path_template) ? api_path.path_template : api_path.to_s
+
+        contexts.find { |ctx| ctx.path_template == template }
+      end
+
+      def narrow(candidates)
+        narrowed = candidates.select { |ctx| yield(ctx) }
+
+        narrowed.empty? ? candidates : narrowed
+      end
+
+      def keys_of(params)
+        params.keys.map(&:to_s)
+      end
+
+      def ambiguity_message(matches, method, owner)
+        paths = matches.map { |ctx| ctx.path_template.inspect }.join(", ")
+
+        "#{method.to_s.upcase} matches more than one api_path in #{owner}: #{paths}. " \
+          "Requests are matched on the verb, the path params supplied and the declared " \
+          "response status, none of which tell these apart. Pass api_path: to pick one, " \
+          "or declare each api_path in its own class or nested describe block."
+      end
+
+      def unknown_path_message(contexts, api_path, owner)
+        template = api_path.respond_to?(:path_template) ? api_path.path_template : api_path.to_s
+        declared = contexts.map { |ctx| ctx.path_template.inspect }.join(", ")
+
+        "No api_path #{template.inspect} declared in #{owner}. " \
+          "Declared: #{declared.empty? ? "none" : declared}."
+      end
+    end
+  end
+end

data/lib/openapi_ruby/adapters/minitest.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "openapi_ruby"
+require_relative "context_resolution"
 require "cgi"
 require "uri"
 
@@ -20,16 +21,30 @@ module OpenapiRuby
           end
 
           def api_path(template, &block)
+            guard_single_api_path!(template)
+
             context = OpenapiRuby::DSL::Context.new(template, schema_name: _openapi_schema_name)
             context.instance_eval(&block) if block
             self._openapi_contexts = _openapi_contexts + [context]
             OpenapiRuby::DSL::MetadataStore.register(context)
             context
           end
+
+          private def guard_single_api_path!(template)
+            return unless OpenapiRuby.configuration.single_api_path_per_class
+
+            existing = _openapi_contexts.first
+            return if existing.nil?
+
+            raise OpenapiRuby::MultipleApiPaths,
+              "#{name || self} already declares api_path #{existing.path_template.inspect}; " \
+              "declare #{template.inspect} in its own class."
+          end
         end
 
-        def assert_api_response(method, expected_status, params: {}, headers: {}, body: nil, path_params: {}, &block)
-          context = find_context_for(method, path_params)
+        def assert_api_response(method, expected_status, params: {}, headers: {}, body: nil, path_params: {},
+          api_path: nil, &block)
+          context = find_context_for(method, path_params, params, expected_status, api_path)
           raise OpenapiRuby::Error, "No api_path defined for #{method.upcase} in #{self.class}" unless context
 
           operation = context.operations[method.to_s]
@@ -123,18 +138,11 @@ module OpenapiRuby
 
         private
 
-        def find_context_for(method, path_params)
-          has_path_params = path_params.any?
-
-          self.class._openapi_contexts.find do |ctx|
-            next false unless ctx.operations.key?(method.to_s)
-
-            if has_path_params
-              ctx.path_template.include?("{")
-            else
-              !ctx.path_template.include?("{")
-            end
-          end
+        def find_context_for(method, path_params, params, expected_status, api_path)
+          OpenapiRuby::Adapters::ContextResolution.resolve(
+            self.class._openapi_contexts, method, path_params,
+            params: params, expected_status: expected_status, api_path: api_path, owner: self.class
+          )
         end
 
         def expand_path(template, params)

data/lib/openapi_ruby/adapters/rspec.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "openapi_ruby"
+require_relative "context_resolution"
 require "cgi"
 require "uri"
 
@@ -21,8 +22,11 @@ module OpenapiRuby
           schema_name = metadata[:openapi_schema_name]
           context = DSL::Context.new(template, schema_name: schema_name)
           context.instance_eval(&block) if block
-          metadata[:openapi_api_contexts] ||= []
-          metadata[:openapi_api_contexts] << context
+          # Replace rather than push: RSpec copies parent metadata into child
+          # groups by reference, so mutating the array in place would leak this
+          # declaration back up to the parent and sideways to its siblings.
+          # Building a new one is what makes a nested describe an actual scope.
+          metadata[:openapi_api_contexts] = (metadata[:openapi_api_contexts] || []) + [context]
           DSL::MetadataStore.register(context)
           context
         end
@@ -123,9 +127,10 @@ module OpenapiRuby
         # Minitest-style assertion: looks up the api_path context, makes the
         # request, validates the response status + body, then yields to the
         # block for additional expectations.
-        def assert_api_response(method, expected_status, params: {}, headers: {}, body: nil, path_params: {}, &block)
+        def assert_api_response(method, expected_status, params: {}, headers: {}, body: nil, path_params: {},
+          api_path: nil, &block)
           meta = ::RSpec.current_example.metadata
-          context = find_api_context_for(meta, method, path_params)
+          context = find_api_context_for(meta, method, path_params, params, expected_status, api_path)
           raise OpenapiRuby::Error, "No api_path defined for #{method.upcase} in this example group" unless context
 
           operation = context.operations[method.to_s]
@@ -334,19 +339,14 @@ module OpenapiRuby
 
         private
 
-        def find_api_context_for(metadata, method, path_params)
+        def find_api_context_for(metadata, method, path_params, params, expected_status, api_path)
           contexts = find_in_metadata(metadata, :openapi_api_contexts) || []
-          has_path_params = path_params.any?
 
-          contexts.find do |ctx|
-            next false unless ctx.operations.key?(method.to_s)
-
-            if has_path_params
-              ctx.path_template.include?("{")
-            else
-              !ctx.path_template.include?("{")
-            end
-          end
+          OpenapiRuby::Adapters::ContextResolution.resolve(
+            contexts, method, path_params,
+            params: params, expected_status: expected_status, api_path: api_path,
+            owner: metadata[:full_description] || "this example group"
+          )
         end
 
         def expand_path(template, params)

data/lib/openapi_ruby/configuration.rb

@@ -18,6 +18,12 @@ module OpenapiRuby
     # Middleware (runtime validation)
     attr_accessor :request_validation, :response_validation, :coerce_params
 
+    # Style 2 only: require each test class to declare a single api_path.
+    # Off by default — resolution handles more than one path per class, so this
+    # is for suites that want the convention enforced anyway.
+    # See Adapters::ContextResolution for how a request is matched.
+    attr_accessor :single_api_path_per_class
+
     # Test DSL: validate that requests match the declared operation before sending.
     # Enabled by default; set to false to disable.
     attr_accessor :test_request_validation
@@ -51,6 +57,7 @@ module OpenapiRuby
       @response_validation = :disabled
       @coerce_params = true
       @test_request_validation = true
+      @single_api_path_per_class = false
       @schema_output_dir = "openapi"
       @schema_output_format = :yaml
       @ui_enabled = false

data/lib/openapi_ruby/errors.rb

@@ -14,6 +14,13 @@ module OpenapiRuby
     end
   end
 
+  # Raised when a Style 2 request matches more than one declared api_path.
+  class AmbiguousApiPath < Error; end
+
+  # Raised when a class declares a second api_path and
+  # `config.single_api_path_per_class` is on.
+  class MultipleApiPaths < Error; end
+
   class SchemaValidationError < Error
     attr_reader :validation_errors
 

data/lib/openapi_ruby/generator/rake_task_support.rb

@@ -42,12 +42,15 @@ module OpenapiRuby
         end
       end
 
-      # Prepended to every generated script. Loading the consumer's test files
-      # must not run them — see AutorunSuppressor.
+      # 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
 

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.2"
+  VERSION = "4.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openapi-ruby
 version: !ruby/object:Gem::Version
-  version: 4.0.2
+  version: 4.1.0
 platform: ruby
 authors:
 - Morten Hartvig
@@ -88,6 +88,7 @@ files:
 - lib/generators/openapi_ruby/install/templates/openapi_helper.rb.tt
 - lib/openapi-ruby.rb
 - lib/openapi_ruby.rb
+- lib/openapi_ruby/adapters/context_resolution.rb
 - lib/openapi_ruby/adapters/minitest.rb
 - lib/openapi_ruby/adapters/rspec.rb
 - lib/openapi_ruby/components/base.rb
@@ -108,6 +109,7 @@ files:
 - 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