openapi-ruby 4.0.3 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4bf806084ec440728b07b1cb5105c2e2f8529852b143a087bb919111afd6498
-  data.tar.gz: d73357f612fa69222d354a2f122a496c63bf8d8259ddb15bdfb38c898c7fb335
+  metadata.gz: 7990b0f6b4af407b5df408029221d095428b91e0f0cc71f798f77e6d37901eb5
+  data.tar.gz: 4514fb71405d81e25a2e079e9e0ebcb03110f1430c327be386fd4d63c336eff1
 SHA512:
-  metadata.gz: ea9f2ab82f0cdae01a6a578daa13f7274914a77b2476ba4ff7bbaf4cfd991ea685c608dcd71eac23bb2bc9ebf0ce35d0ac764b63a89bbb35add7e95c73a9d048
-  data.tar.gz: b940f94f696df915e90eccc593ae3901b1bc63229b4158391da62ffddb7fef1932a788358c1bffe771054f3e7d5f68faae36ff549ebb2c1166c078ed8ee58c66
+  metadata.gz: 6f2f27ba8f415683fb454b707e90eec7b9bb3f6adf5c5c1835b1f4002d83afb898414d4a735cc372d9b6a5a47f636c7aa2d0bf24dee092c5fe2b40180828a218
+  data.tar.gz: 666bb48fd0aaa60c3b25ab242e180735513416db9b34aaa22ec9dcabd54cc0dbcb2aeb5a50d36c7ae860f68fda83cb5261e0706561decce219f657fde4003853

data/README.md

@@ -507,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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenapiRuby
-  VERSION = "4.0.3"
+  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.3
+  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