rspec-openapi 0.35.0 → 0.36.0

data/lib/rspec/openapi/rspec_hooks.rb

@@ -10,16 +10,24 @@ RSpec.configuration.after(:each) do |example|
   if RSpec::OpenAPI.example_types.include?(example.metadata[:type]) && example.metadata[:openapi] != false
     path = RSpec::OpenAPI.path.then { |p| p.is_a?(Proc) ? p.call(example) : p }
     record = RSpec::OpenAPI::RecordBuilder.build(self, example: example, extractor: SharedHooks.find_extractor)
-    RSpec::OpenAPI.path_records[path] << record if record
+    if record
+      RSpec::OpenAPI.path_records[path] << record
+      RSpec::OpenAPI::PartialRun.record_file(example.metadata[:absolute_file_path])
+    end
   end
 end
 
 RSpec.configuration.after(:suite) do
-  result_recorder = RSpec::OpenAPI::ResultRecorder.new(RSpec::OpenAPI.path_records)
+  partial = RSpec::OpenAPI::PartialRun.rspec?
+  result_recorder = RSpec::OpenAPI::ResultRecorder.new(RSpec::OpenAPI.path_records, partial: partial)
   result_recorder.record_results!
+  reporter = RSpec.configuration.reporter
+  if (notice = RSpec::OpenAPI::PartialRun.notice(partial))
+    reporter.message notice
+  end
   if result_recorder.errors?
     error_message = result_recorder.error_message
     colorizer = RSpec::Core::Formatters::ConsoleCodes
-    RSpec.configuration.reporter.message colorizer.wrap(error_message, :failure)
+    reporter.message colorizer.wrap(error_message, :failure)
   end
 end

data/lib/rspec/openapi/schema_builder/build_context.rb

@@ -6,14 +6,28 @@ class << RSpec::OpenAPI::SchemaBuilder
   # a value at a given path under a record's request/response side.
   #
   # Positional members: one is built per property of every body, and
-  # keyword_init would add a keyword hash to each.
-  BuildContext = Struct.new(:record, :context, :path, :key) do
+  # keyword_init would add a keyword hash to each. The path is only ever looked
+  # up in the enum and additionalProperties maps of the record, so it is built
+  # for a side of a record that holds one.
+  BuildContext = Struct.new(:record, :context, :path, :key, :lookups) do
+    def self.root(record, context, path = nil, key = nil)
+      lookups = record[ENUM_MEMBERS.fetch(context)] ||
+                OVERRIDE_MEMBERS.any? { |_kind, members| record[members.fetch(context)] }
+      new(record, context, path, key, lookups)
+    end
+
     def descend(child_key)
-      self.class.new(record, context, path ? "#{path}.#{child_key}" : child_key.to_s, child_key)
+      self.class.new(record, context, child_path(child_key), child_key, lookups)
+    end
+
+    def child_path(child_key)
+      return nil unless lookups
+
+      path ? "#{path}.#{child_key}" : child_key.to_s
     end
 
     def for_array_items
-      self.class.new(record, context, path, nil)
+      self.class.new(record, context, path, nil, lookups)
     end
   end
   private_constant :BuildContext

data/lib/rspec/openapi/schema_builder/variation_merger.rb

@@ -27,11 +27,10 @@ class << RSpec::OpenAPI::SchemaBuilder
     end
 
     def merge_non_object_item_variations(schemas)
-      nullable_only = ->(schema) { schema.keys == [:nullable] }
-      typed = schemas.reject(&nullable_only)
+      typed = schemas.reject { |schema| nullable_only?(schema) }
 
       merged = typed.size == 1 ? typed.first.dup : merge_multi(typed)
-      merged[:nullable] = true if schemas.any?(&nullable_only) && merged.is_a?(Hash)
+      merged[:nullable] = true if schemas.any? { |schema| nullable_only?(schema) } && merged.is_a?(Hash)
       merged
     end
 
@@ -43,19 +42,32 @@ class << RSpec::OpenAPI::SchemaBuilder
     def merge_property_variations(variations, allow_recursive_merge:)
       property_keys(variations).each_with_object({}) do |key, merged_props|
         all = variations.map { |v| v[:properties]&.[](key) }
-        prop_variations = all.reject { |p| p.nil? || p.keys == [:nullable] }
+        read_only = lift_read_only!(all)
+        prop_variations = all.reject { |p| p.nil? || nullable_only?(p) }
         has_nullable = nullable_present?(all, recursive: allow_recursive_merge)
 
         next if prop_variations.empty? && !has_nullable
 
-        merged_props[key] = merge_single_property(prop_variations, has_nullable,
-                                                  variations_total: variations.size,
-                                                  allow_recursive_merge: allow_recursive_merge,)
+        merged = merge_single_property(prop_variations, has_nullable,
+                                       variations_total: variations.size,
+                                       allow_recursive_merge: allow_recursive_merge,)
+        merged[:readOnly] = read_only unless read_only.nil?
+        merged_props[key] = merged
       end
     end
 
     private
 
+    # The variations of one property come from one side of one exchange, so
+    # they agree on readOnly. The merge rebuilds the schema, so the caller puts
+    # it back on the result, beside a oneOf like nullable. The schemas are the
+    # builder's own, so the flag comes off them in place.
+    def lift_read_only!(all)
+      read_only = all.find { |p| p.is_a?(Hash) && p.key?(:readOnly) }&.[](:readOnly)
+      all.each { |p| p&.delete(:readOnly) } unless read_only.nil?
+      read_only
+    end
+
     def merge_object_variations(variations)
       merged = { type: 'object' }
       if variations.any? { |v| v.key?(:properties) }
@@ -74,7 +86,10 @@ class << RSpec::OpenAPI::SchemaBuilder
     end
 
     def property_keys(variations)
-      variations.flat_map { |v| v[:properties]&.keys || [] }.uniq
+      keys = []
+      variations.each { |v| v[:properties]&.each_key { |key| keys << key } }
+      keys.uniq!
+      keys
     end
 
     # `recursive` mirrors merge_variations' original rule that also treats
@@ -82,10 +97,14 @@ class << RSpec::OpenAPI::SchemaBuilder
     # looks at outright nil or `{ nullable: true }` markers.
     def nullable_present?(all_props, recursive:)
       all_props.any? do |p|
-        p.nil? || (p.is_a?(Hash) && (p.keys == [:nullable] || (recursive && p[:nullable] == true)))
+        p.nil? || (p.is_a?(Hash) && (nullable_only?(p) || (recursive && p[:nullable] == true)))
       end
     end
 
+    def nullable_only?(schema)
+      schema.size == 1 && schema.key?(:nullable)
+    end
+
     def merge_single_property(prop_variations, has_nullable, variations_total:, allow_recursive_merge:)
       return { nullable: true } if prop_variations.empty?
 

data/lib/rspec/openapi/schema_builder.rb

@@ -7,6 +7,7 @@ require_relative 'schema_builder/variation_merger'
 class << RSpec::OpenAPI::SchemaBuilder
   # Record members holding the per-context lookup maps, by context (and kind).
   ENUM_MEMBERS = { request: :request_enum, response: :response_enum }.freeze
+  READ_ONLY_MEMBERS = { request: :request_read_only, response: :response_read_only }.freeze
   OVERRIDE_MEMBERS = {
     additional_properties: {
       request: :request_additional_properties, response: :response_additional_properties,
@@ -16,13 +17,20 @@ class << RSpec::OpenAPI::SchemaBuilder
     },
   }.freeze
 
+  # GET and DELETE never have a request body in OpenAPI.
+  BODYLESS_METHODS = ['delete', 'get'].freeze
+
+  # The schema holds symbol keys like the document, and nothing of the record:
+  # the data it carries is copied, so the merger can take the schema over.
+  #
   # @param [RSpec::OpenAPI::Record] record
   # @return [Hash]
   def build(record)
+    http_method = record.http_method.downcase
     {
       paths: {
-        normalize_path(record.path) => {
-          record.http_method.downcase => build_operation(record),
+        normalize_path(record.path).to_sym => {
+          http_method.to_sym => build_operation(record, http_method),
         },
       },
     }
@@ -30,20 +38,19 @@ class << RSpec::OpenAPI::SchemaBuilder
 
   private
 
-  def build_operation(record)
-    http_method = record.http_method.downcase
-    # GET and DELETE never have a request body in OpenAPI.
-    request_body = ['delete', 'get'].include?(http_method) ? nil : build_request_body(record)
-    {
+  def build_operation(record, http_method)
+    operation = {
       summary: record.summary,
-      tags: record.tags,
+      tags: copy(record.tags),
       operationId: record.operation_id,
-      security: record.security,
+      security: copy(record.security),
       deprecated: record.deprecated ? true : nil,
       parameters: build_parameters(record),
-      requestBody: request_body,
-      responses: { record.status.to_s => build_response(record) },
-    }.compact
+      requestBody: BODYLESS_METHODS.include?(http_method) ? nil : build_request_body(record),
+      responses: { record.status.to_s.to_sym => build_response(record) },
+    }
+    operation.compact!
+    operation
   end
 
   def build_response(record)
@@ -67,18 +74,18 @@ class << RSpec::OpenAPI::SchemaBuilder
   def build_content(record)
     disposition = normalize_content_disposition(record.response_content_disposition)
     content_type = normalize_content_type(record.response_content_type)
-    ctx = BuildContext.new(record, :response)
+    ctx = BuildContext.root(record, :response)
 
     if RSpec::OpenAPI.supports_item_schema? && RSpec::OpenAPI.sequential_media_type?(content_type)
       item_schema = build_stream_item_schema(record.response_body, content_type, ctx)
-      return { content_type => { itemSchema: item_schema } } if item_schema
+      return { content_type.to_sym => { itemSchema: item_schema } } if item_schema
     end
 
     schema = build_property(record.response_body, ctx, disposition: disposition)
     example = response_example(record, disposition: disposition)
 
     body = build_example_body(schema, record, mode: record.response_example_mode, example: example)
-    { content_type => body }
+    { content_type.to_sym => body }
   end
 
   def build_stream_item_schema(raw, content_type, ctx)
@@ -96,18 +103,30 @@ class << RSpec::OpenAPI::SchemaBuilder
 
     case mode
     when :multiple
-      { schema: schema, examples: { record.example_key => build_named_example(record, example) } }
+      { schema: schema, examples: { example_name(record) => build_named_example(record, example) } }
     else
       # :single (default)
       # :single may emit nil example or nil _example_summary; compact strips them.
-      { schema: schema, example: example, **example_metadata(record) }.compact
+      body = {
+        schema: schema,
+        example: example,
+        _example_key: record.example_key,
+        _example_summary: example_summary(record),
+      }
+      body.compact!
+      body
     end
   end
 
   def response_example(record, disposition:)
-    return nil if !example_enabled?(record) || disposition
+    return nil if !example_enabled?(record) || disposition || record.response_example_mode == :none
+
+    build_example(record.response_body)
+  end
 
-    record.response_body
+  # Named like the loader names the examples it reads back.
+  def example_name(record)
+    RSpec::OpenAPI::ExampleKey.normalize(record.example_key).to_sym
   end
 
   def build_named_example(record, value)
@@ -115,10 +134,6 @@ class << RSpec::OpenAPI::SchemaBuilder
     summary ? { summary: summary, value: value } : { value: value }
   end
 
-  def example_metadata(record)
-    { _example_key: record.example_key, _example_summary: example_summary(record) }
-  end
-
   def example_summary(record)
     return nil unless RSpec::OpenAPI.enable_example_summary
     return nil if record.example_name.nil? || record.example_name.empty?
@@ -134,15 +149,12 @@ class << RSpec::OpenAPI::SchemaBuilder
     parameters = record.path_params.map do |key, value|
       build_parameter(key, value, location: 'path', record: record)
     end
-
-    parameters += flatten_query_params(record.query_params).map do |key, value|
-      build_parameter(key, value, location: 'query', record: record)
+    flatten_query_params(record.query_params).each do |key, value|
+      parameters << build_parameter(key, value, location: 'query', record: record)
     end
-
-    parameters += record.request_headers.map do |key, value|
-      build_parameter(key, value, location: 'header', record: record)
+    record.request_headers.each do |key, value|
+      parameters << build_parameter(key, value, location: 'header', record: record)
     end
-
     parameters.empty? ? nil : parameters
   end
 
@@ -152,21 +164,26 @@ class << RSpec::OpenAPI::SchemaBuilder
     is_query = location == 'query'
     required = is_query ? record.required_request_params.include?(key) : true
     cast = try_cast(value)
-    ctx = BuildContext.new(record, :request, key.to_s, key)
-    {
-      name: key.to_s,
+    name = key.to_s
+    ctx = BuildContext.root(record, :request, name, key)
+    parameter = {
+      name: name,
       in: location,
       required: required,
       schema: build_property(cast, ctx),
       example: (cast if example_enabled?(record)),
-    }.compact
+    }
+    parameter.compact!
+    parameter
   end
 
   def build_response_headers(record)
-    record.response_headers.to_h do |key, value|
-      ctx = BuildContext.new(record, :response, key.to_s, key)
-      [key, { schema: build_property(try_cast(value), ctx) }]
+    headers = {}
+    record.response_headers.each do |key, value|
+      ctx = BuildContext.root(record, :response, key.to_s, key)
+      headers[key.to_sym] = { schema: build_property(try_cast(value), ctx) }
     end
+    headers
   end
 
   def flatten_query_params(params, parent_key = nil)
@@ -186,12 +203,12 @@ class << RSpec::OpenAPI::SchemaBuilder
     return nil if record.status >= 400 && record.request_example_mode != :multiple
 
     content_type = normalize_content_type(record.request_content_type)
-    ctx = BuildContext.new(record, :request)
+    ctx = BuildContext.root(record, :request)
     schema = build_property(record.request_params, ctx)
-    example = example_enabled?(record) ? build_example(record.request_params) : nil
+    example = build_example(record.request_params) if example_enabled?(record) && record.request_example_mode != :none
 
     body = build_example_body(schema, record, mode: record.request_example_mode, example: example)
-    { content: { content_type => body } }
+    { content: { content_type.to_sym => body } }
   end
 
   def build_property(value, ctx, disposition: nil)
@@ -214,14 +231,25 @@ class << RSpec::OpenAPI::SchemaBuilder
     if override.is_a?(Hash) && !override.empty?
       # Schema override: the object's keys are dynamic — replace captured
       # `properties` / `required` with the supplied dictionary value schema.
-      property[:additionalProperties] = override
+      property[:additionalProperties] = copy(override)
       return
     end
 
+    # Only an object property can be readOnly. A request that sends a candidate
+    # says false, which wins where the two sides meet in one schema (see
+    # SchemaMerger).
+    read_only = ctx.record[READ_ONLY_MEMBERS.fetch(ctx.context)]
     properties = {}
-    value.each { |k, v| properties[k] = build_property(v, ctx.descend(k)) }
+    required = []
+    value.each do |k, v|
+      child = build_property(v, ctx.descend(k))
+      name = k.to_s
+      child[:readOnly] = ctx.context == :response if read_only&.[](name)
+      properties[name.to_sym] = child
+      required << name
+    end
     property[:properties] = properties
-    property[:required] = properties.keys
+    property[:required] = required
     apply_additional_properties(property, override,
                                 infer_override(ctx.path, ctx.record, ctx.context, :hybrid_additional_properties),)
   end
@@ -235,7 +263,7 @@ class << RSpec::OpenAPI::SchemaBuilder
     if [true, false].include?(override)
       property[:additionalProperties] = override
     elsif hybrid_override.is_a?(Hash) && !hybrid_override.empty?
-      property[:additionalProperties] = hybrid_override
+      property[:additionalProperties] = copy(hybrid_override)
     end
   end
 
@@ -256,7 +284,7 @@ class << RSpec::OpenAPI::SchemaBuilder
                end
              end
 
-    result[:enum] = enum if enum
+    result[:enum] = copy(enum) if enum
     result
   end
 
@@ -296,31 +324,36 @@ class << RSpec::OpenAPI::SchemaBuilder
     Integer(value, exception: false) || value
   end
 
+  # A copy of a recorded value with symbol keys, and the filename of an upload.
   def build_example(value)
-    return nil if value.nil?
-
-    adjust_value(value.dup)
-  end
-
-  def adjust_params(hash)
-    hash.transform_values! { |v| adjust_value(v) }
-  end
-
-  def adjust_value(value)
     case value
+    when Hash
+      example = {}
+      value.each { |key, item| example[key.to_sym] = build_example(item) }
+      example
+    when Array then value.map { |item| build_example(item) }
     when ActionDispatch::Http::UploadedFile then value.original_filename
-    when Hash then adjust_params(value)
-    when Array then value.map { |item| adjust_value(item) }
     else value
     end
   end
 
+  # A record may hold what the metadata of a whole example group holds.
+  def copy(value)
+    RSpec::OpenAPI::KeyTransformer.symbolize(value)
+  end
+
+  # gsub copies the path even when nothing matches.
   def normalize_path(path)
+    return path unless path.include?(':')
+
     path.gsub(%r{/:([^:/]+)}, '/{\1}')
   end
 
+  # sub copies the content type even when it carries no parameters.
   def normalize_content_type(content_type)
-    content_type&.sub(/;.+\z/, '')
+    return content_type unless content_type&.include?(';')
+
+    content_type.sub(/;.+\z/, '')
   end
 
   # Same logic as normalize_content_type – strips header parameters after ';'

data/lib/rspec/openapi/schema_cleaner.rb

@@ -16,6 +16,12 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
     cleanup_one_of_properties!(base, spec, 'components.schemas.*')
   end
 
+  # The request and response bodies, where most of the cleanup happens.
+  MEDIA_TYPE_SELECTORS = [
+    'paths.*.*.requestBody.content.application/json',
+    'paths.*.*.responses.*.content.application/json',
+  ].freeze
+
   # Cleanup specific elements that exists in the base but not in the spec
   #
   # @param [Hash] base
@@ -30,22 +36,16 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
     # cleanup parameters
     cleanup_array!(base, spec, 'paths.*.*.parameters', [:name, :in])
 
-    # cleanup requestBody
-    cleanup_hash!(base, spec, 'paths.*.*.requestBody.content.application/json.schema.properties.*')
-    cleanup_hash!(base, spec, 'paths.*.*.requestBody.content.application/json.example.*')
-    cleanup_hash!(base, spec, 'paths.*.*.requestBody.content.application/json.examples.*')
-
-    # cleanup responses
-    cleanup_hash!(base, spec, 'paths.*.*.responses.*.content.application/json.schema.properties.*')
-    cleanup_hash!(base, spec, 'paths.*.*.responses.*.content.application/json.example.*')
-    cleanup_hash!(base, spec, 'paths.*.*.responses.*.content.application/json.examples.*')
-
-    # cleanup properties of each variant once a body became a oneOf
-    cleanup_one_of_properties!(base, spec, 'paths.*.*.requestBody.content.application/json.schema')
-    cleanup_one_of_properties!(base, spec, 'paths.*.*.responses.*.content.application/json.schema')
+    # cleanup request and response bodies, each walked down to once
+    MEDIA_TYPE_SELECTORS.each do |selector|
+      RSpec::OpenAPI::HashHelper.each_matched(base, spec, selector) do |_parent, _key, media_type, fresh|
+        cleanup_media_type!(media_type, fresh)
+      end
+    end
 
-    # cleanup temporary fields used for internal processing
-    cleanup_temporary_fields!(base)
+    # A full run decides readOnly anew, so a property no request sends any
+    # more stops being held at false.
+    RSpec::OpenAPI::HashHelper.each_schema(base.dig(:components, :schemas)) { |schema| delete_false_read_only!(schema) }
 
     base
   end
@@ -62,19 +62,58 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
     end
   end
 
-  # A recorded example is data, so a field in it named `required` stays however
-  # it is shaped.
-  def cleanup_empty_required_array!(base)
-    [base.dig(:components, :schemas), base[:paths]].each do |root|
-      RSpec::OpenAPI::HashHelper.each_schema(root) do |schema|
-        # "required" array  must not be present if empty
-        schema.delete(:required) if schema.key?(:properties) && schema[:required] && schema[:required].empty?
-      end
+  # One walk over the schemas once the components are updated, which also drops
+  # the fields the builder left for the merge. `readOnly: false` is how a
+  # request says it sends a candidate property. A component shared by a request
+  # and a response keeps it, or a later partial run that sees only the response
+  # would flip it back to true. Inline under paths each side has its own
+  # schema, so there it says nothing.
+  def cleanup_schemas!(base)
+    RSpec::OpenAPI::HashHelper.each_schema(base.dig(:components, :schemas)) do |schema|
+      delete_temporary_fields!(schema)
+      delete_empty_required!(schema)
+    end
+    RSpec::OpenAPI::HashHelper.each_schema(base[:paths]) do |schema|
+      delete_temporary_fields!(schema)
+      delete_empty_required!(schema)
+      delete_false_read_only!(schema)
     end
   end
 
   private
 
+  # The description of a response whose example is not recorded is provisional,
+  # so it stays only where no documented test set one.
+  def delete_temporary_fields!(schema)
+    schema.delete(:_example_key)
+    schema.delete(:_example_summary)
+    schema.delete(:_example_name)
+    return unless (fallback = schema.delete(:_fallback_description))
+
+    schema[:description] ||= fallback
+  end
+
+  # A recorded example is data, so a field in it named `required` stays however
+  # it is shaped. An empty `required` must not be present.
+  def delete_empty_required!(schema)
+    schema.delete(:required) if schema.key?(:properties) && schema[:required] && schema[:required].empty?
+  end
+
+  def delete_false_read_only!(schema)
+    schema.delete(:readOnly) if schema[:readOnly] == false
+  end
+
+  # The selectors are relative to the media type. A media type the spec does
+  # not hold has no fresh counterpart, and all of its entries are stale.
+  def cleanup_media_type!(media_type, fresh)
+    cleanup_hash!(media_type, fresh, 'schema.properties.*')
+    cleanup_hash!(media_type, fresh, 'example.*')
+    cleanup_hash!(media_type, fresh, 'examples.*')
+
+    # cleanup properties of each variant once a body became a oneOf
+    cleanup_one_of_properties!(media_type, fresh, 'schema')
+  end
+
   # Security sits on operations, the hashes under a path item: a non-standard
   # method is still inline here and only moves under additionalOperations later.
   def each_operation(base)
@@ -85,26 +124,6 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
     end
   end
 
-  # Recursively remove temporary fields like :_example_key and :_example_name from the schema.
-  # Every caller has already established that it holds a Hash.
-  def cleanup_temporary_fields!(hash)
-    hash.delete(:_example_key)
-    hash.delete(:_example_summary)
-    hash.delete(:_example_name)
-    if (fallback = hash.delete(:_fallback_description))
-      hash[:description] ||= fallback
-    end
-
-    hash.each_value do |value|
-      case value
-      when Hash
-        cleanup_temporary_fields!(value)
-      when Array
-        value.each { |item| cleanup_temporary_fields!(item) if item.is_a?(Hash) }
-      end
-    end
-  end
-
   def remove_parameters_conflicting_with_security_scheme!(path_definition, security_scheme, security_scheme_name)
     security = path_definition[:security]
     return if !security || security.empty?
@@ -121,9 +140,7 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
   def cleanup_array!(base, spec, selector, fields_for_identity)
     identity = ->(obj) { fields_for_identity.map { |field| obj[field] } }
 
-    RSpec::OpenAPI::HashHelper.matched_paths(base, selector).each do |paths|
-      target_array = base.dig(*paths)
-      spec_array = spec.dig(*paths)
+    RSpec::OpenAPI::HashHelper.each_matched(base, spec, selector) do |_parent, _key, target_array, spec_array|
       next unless target_array.is_a?(Array) && spec_array.is_a?(Array)
 
       spec_identities = Set.new(spec_array.map(&identity))
@@ -137,10 +154,11 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
   end
 
   def cleanup_one_of_properties!(base, spec, selector)
-    RSpec::OpenAPI::HashHelper.matched_paths(base, selector).each do |paths|
-      variants = base.dig(*paths, :oneOf)
-      fresh = spec.dig(*paths)
-      next unless variants.is_a?(Array) && fresh.is_a?(Hash)
+    RSpec::OpenAPI::HashHelper.each_matched(base, spec, selector) do |_parent, _key, schema, fresh|
+      next unless schema.is_a?(Hash) && fresh.is_a?(Hash)
+
+      variants = schema[:oneOf]
+      next unless variants.is_a?(Array)
 
       variants.each { |variant| cleanup_variant_properties!(variant, variants, fresh) }
     end
@@ -161,14 +179,13 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
     variant[:properties].delete_if { |name, _| counterpart.dig(:properties, name).nil? }
   end
 
-  # Every selector above names at least two segments, so a matched path always
-  # has a parent to delete the entry from.
+  # The stale entries are deleted after the walk, which iterates their parents.
   def cleanup_hash!(base, spec, selector)
-    RSpec::OpenAPI::HashHelper.matched_paths(base, selector).each do |paths|
-      exist_in_base = !base.dig(*paths).nil?
-      not_in_spec = spec.dig(*paths).nil?
-      base.dig(*paths[0..-2]).delete(paths.last) if exist_in_base && not_in_spec
+    stale = nil
+    RSpec::OpenAPI::HashHelper.each_matched(base, spec, selector) do |parent, key, value, counterpart|
+      (stale ||= []) << [parent, key] if !value.nil? && counterpart.nil?
     end
+    stale&.each { |parent, key| parent.delete(key) }
     base
   end
 end