rspec-openapi 0.33.1 → 0.35.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb54f98b3234ebee5ea46c0c703f094265d37c17f8fc1c8dcfec5c1f70c88667
-  data.tar.gz: 30972c7a4dd8387e1db47d954b3b5e380ee9a0d6282981ba73d14007e5fcdce8
+  metadata.gz: d7298e79ff60a23925281c724390eed37544bef37a47f7ba85e6f5ef2d28bf3f
+  data.tar.gz: b1798ffc05aa81f206b4f50e5fffeb6317ac902e113c1c3449bf1f0ed4be437d
 SHA512:
-  metadata.gz: 19552292efc3339da373ca62b6e7c20ce23546d5ba81bd7b245ce6796dca729a12fd4138c905b11d90b9892e67f0a3abc18f15eaf7ea8f153f3a4c4b5f76de3c
-  data.tar.gz: ff754813db11c90118d4169428547b84c7c5a7163384124e94c15eefacff9dd62e701cc6c0c37716cb889dccba061086858ccc32161ed41f4a275d2a0eb8fcff
+  metadata.gz: 8d5b3eb347258591c559c26f4450179c7a329a67bc1a6b01e7f92b1666dd8ab251c604f93ac28c92387277649d5b17b94d37a38be31875f86872028e431e6fad
+  data.tar.gz: 4ee74f1f40a64081044245d88dfe01ac43a40ef397467477e99cf54ea3368b2af080c44712f3873727989cf94e7c27229e2aaed900db0df58f1cfc2d0b818005

data/lib/rspec/openapi/components_updater.rb

@@ -10,14 +10,26 @@ class << RSpec::OpenAPI::ComponentsUpdater = Object.new
   def update!(base, fresh)
     # Top-level schema: Used as the body of request or response
     top_level_refs = paths_to_top_level_refs(base)
-    return if top_level_refs.empty?
-
     fresh_schemas = build_fresh_schemas(top_level_refs, base, fresh)
 
-    # Nested schema: References in Top-level schemas. May contain some top-level schema.
-    generated_schema_names = fresh_schemas.keys
-    nested_refs = find_non_top_level_nested_refs(base, generated_schema_names)
-    nested_refs.each do |paths|
+    # Nested schema: References in top-level schemas. May contain some top-level schema.
+    # A parent to dig fresh data out of only exists once some top-level schema was found.
+    apply_component_nested_refs!(fresh_schemas, base) unless top_level_refs.empty?
+
+    # Nested schema: References inline in a request/response body, not inside a component.
+    # Unlike the above, this doesn't depend on any top-level schema being found first.
+    apply_inline_nested_refs!(fresh_schemas, base, fresh)
+
+    return if fresh_schemas.empty?
+
+    RSpec::OpenAPI::SchemaMerger.merge_normalized!(base, { components: { schemas: fresh_schemas } })
+    RSpec::OpenAPI::SchemaCleaner.cleanup_components_schemas!(base, { components: { schemas: fresh_schemas } })
+  end
+
+  private
+
+  def apply_component_nested_refs!(fresh_schemas, base)
+    find_non_top_level_nested_refs(base, fresh_schemas.keys).each do |paths|
       # Slice between the parent name and the element before "$ref"
       # ["components", "schema", "Table", "properties", "database",                       "$ref"]
       #  0             1         2 ^....................^
@@ -32,27 +44,60 @@ class << RSpec::OpenAPI::ComponentsUpdater = Object.new
       # Skip if the property using $ref is not found in the parent schema. The property may be removed.
       next if nested_schema.nil?
 
-      schema_name = extract_schema_name(base.dig(*paths)).to_sym
-      fresh_schemas[schema_name] ||= {}
-      RSpec::OpenAPI::SchemaMerger.merge_normalized!(fresh_schemas[schema_name], nested_schema)
+      merge_fresh_schema!(fresh_schemas, base, paths, nested_schema)
     end
+  end
 
-    RSpec::OpenAPI::SchemaMerger.merge_normalized!(base, { components: { schemas: fresh_schemas } })
-    RSpec::OpenAPI::SchemaCleaner.cleanup_components_schemas!(base, { components: { schemas: fresh_schemas } })
+  # No promoted parent schema to dig from here, so pull the fresh data from the same
+  # relative path in the raw document instead.
+  def apply_inline_nested_refs!(fresh_schemas, base, fresh)
+    find_inline_nested_refs(base, fresh_schemas.keys).each do |paths|
+      nested_schema = dig_like(fresh, base, paths[0..-2])
+      next if nested_schema.nil?
+
+      merge_fresh_schema!(fresh_schemas, base, paths, nested_schema)
+    end
   end
 
-  private
+  # Digs fresh along a path of base. This run may have recorded one shape of a
+  # oneOf only, or its variants in another order, so at a variant index the step
+  # picks the fresh variant of the type base has there.
+  def dig_like(fresh, base, paths)
+    node = fresh
+    paths.each_with_index do |step, index|
+      node = if index.positive? && paths[index - 1] == :oneOf
+               RSpec::OpenAPI::HashHelper.variant_of_type(node, base.dig(*paths.take(index + 1), :type))
+             elsif step != :oneOf
+               node[step]
+             else
+               node
+             end
+      return nil unless node.is_a?(Hash)
+    end
+    node
+  end
+
+  def merge_fresh_schema!(fresh_schemas, base, paths, nested_schema)
+    schema_name = extract_schema_name(base.dig(*paths))
+    merge_schema!(fresh_schemas, schema_name, nested_schema)
+  end
 
   def build_fresh_schemas(references, base, fresh)
-    references.inject({}) do |acc, paths|
+    references.each_with_object({}) do |paths, fresh_schemas|
       ref_link = dig_schema(base, paths)[:$ref]
       schema_name = extract_schema_name(ref_link)
       schema_body = dig_schema(fresh, paths.grep_v(Integer))
 
-      RSpec::OpenAPI::SchemaMerger.merge_normalized!(acc, { schema_name => schema_body })
+      merge_schema!(fresh_schemas, schema_name, schema_body)
     end
   end
 
+  # Under a `schemas` key the merger knows it merges schemas, so two shapes of
+  # one component become a oneOf like they would inline.
+  def merge_schema!(fresh_schemas, schema_name, schema)
+    RSpec::OpenAPI::SchemaMerger.merge_normalized!({ schemas: fresh_schemas }, { schemas: { schema_name => schema } })
+  end
+
   def dig_schema(obj, paths)
     # Response code can be an integer
     paths = paths.map { |path| path.is_a?(Integer) ? path : path.to_sym }
@@ -75,12 +120,26 @@ class << RSpec::OpenAPI::ComponentsUpdater = Object.new
   end
 
   def find_non_top_level_nested_refs(base, generated_names)
-    nested_refs = [
-      *RSpec::OpenAPI::HashHelper.matched_paths_deeply_nested(base, 'components.schemas', 'properties.*.$ref'),
-      *RSpec::OpenAPI::HashHelper.matched_paths_deeply_nested(base, 'components.schemas', 'properties.*.items.$ref'),
-      *RSpec::OpenAPI::HashHelper.matched_paths_deeply_nested(base, 'components.schemas', 'oneOf.*.$ref'),
+    nested_refs = RSpec::OpenAPI::HashHelper.matched_paths_deeply_nested(
+      base, 'components.schemas', 'properties.*.$ref', 'properties.*.items.$ref', 'oneOf.*.$ref',
+    )
+    reject_already_generated_refs(nested_refs, base, generated_names)
+  end
+
+  # Like find_non_top_level_nested_refs, but for a $ref inside a schema that's inline
+  # rather than itself a component, so it's not reachable by walking components.schemas.
+  def find_inline_nested_refs(base, generated_names)
+    roots = [
+      'paths.*.*.requestBody.content.application/json.schema',
+      'paths.*.*.responses.*.content.application/json.schema',
     ]
-    # Reject already-generated schemas to reduce unnecessary loop
+    nested_refs = roots.flat_map do |root|
+      RSpec::OpenAPI::HashHelper.matched_paths_deeply_nested(base, root, 'properties.*.$ref', 'properties.*.items.$ref')
+    end
+    reject_already_generated_refs(nested_refs, base, generated_names)
+  end
+
+  def reject_already_generated_refs(nested_refs, base, generated_names)
     nested_refs.reject do |paths|
       ref_link = base.dig(*paths)
       schema_name = extract_schema_name(ref_link)

data/lib/rspec/openapi/hash_helper.rb

@@ -7,56 +7,121 @@ class << RSpec::OpenAPI::HashHelper = Object.new
   # document and filtering. A document built from a large suite holds tens of
   # thousands of nodes and these selectors run dozens of times per build.
   def matched_paths(obj, selector)
-    selector_parts = selector.split('.').map(&:to_sym)
     matches = []
-    collect_matches(obj, selector_parts, 0, [], matches)
+    collect_matches(obj, split_selector(selector), 0, [], matches)
     matches
   end
 
-  def matched_paths_deeply_nested(obj, begin_selector, end_selector)
-    begin_depth = begin_selector.to_s.count('.')
-    end_depth = end_selector.to_s.count('.')
+  # Paths that start with a match of begin_selector and end with a match of an
+  # end selector, with any number of keys in between: the matches of the first
+  # end selector sorted by length, then those of the next, each length in
+  # document order.
+  #
+  # The subtree under a begin match is walked once for all the end selectors,
+  # checking the tail of every path against each. Walking it once per possible
+  # length instead makes this cost the depth of the document times its size.
+  def matched_paths_deeply_nested(obj, begin_selector, *end_selectors)
+    end_parts = end_selectors.map { |selector| split_selector(selector) }
+    matches = end_parts.map { [] }
+    matched_paths(obj, begin_selector).each do |prefix|
+      collect_suffix_matches(obj.dig(*prefix), end_parts, prefix.dup, prefix.size, matches)
+    end
+    matches.flat_map { |found| found.group_by(&:size).sort_by(&:first).flat_map(&:last) }
+  end
 
-    # Every path in obj has all of its prefixes in obj too, so the depths that
-    # occur are exactly 1 up to the deepest one.
-    (1..max_depth(obj)).flat_map do |depth|
-      gap = depth - begin_depth - end_depth
-      next [] if gap.negative?
+  # Keys whose values hold user data, not schemas. Their contents must never be
+  # rewritten, or a recorded example/default that happens to contain a field
+  # named `type` or `nullable` would be silently mangled.
+  DATA_KEYS = [:example, :examples, :default, :enum, :const].freeze
 
-      matched_paths(obj, "#{begin_selector}.#{'*.' * gap}#{end_selector}")
+  # Yields every hash in obj outside the data subtrees in DATA_KEYS, each after
+  # its descendants. The entries of a `properties` map are schemas whatever
+  # their names, so the map itself is skipped and each entry is yielded.
+  def each_schema(obj, &block)
+    case obj
+    when Hash
+      obj.each do |key, value|
+        if key == :properties && value.is_a?(Hash)
+          value.each_value { |property| each_schema(property, &block) }
+        elsif !DATA_KEYS.include?(key)
+          each_schema(value, &block)
+        end
+      end
+      yield obj
+    when Array
+      obj.each { |value| each_schema(value, &block) }
     end
   end
 
+  # The variant of a schema that has the type, where a schema without a oneOf
+  # is its only variant.
+  def variant_of_type(schema, type)
+    (schema[:oneOf] || [schema]).find { |variant| variant.is_a?(Hash) && variant[:type] == type }
+  end
+
   private
 
-  def collect_matches(obj, selector_parts, depth, prefix, matches)
+  def split_selector(selector)
+    selector.split('.').map(&:to_sym)
+  end
+
+  # `path` is the stack of keys from the root to obj, pushed and popped in
+  # place, so a path is only ever copied for a match.
+  def collect_matches(obj, selector_parts, depth, path, matches)
     part = selector_parts[depth]
     last = depth == selector_parts.size - 1
 
     each_child(obj) do |key, value|
       next unless part == :* || part == key
 
-      path = [*prefix, key]
+      path.push(key)
       if last
-        matches << path
+        matches << path.dup
       else
         collect_matches(value, selector_parts, depth + 1, path, matches)
       end
+      path.pop
     end
   end
 
-  def each_child(obj)
-    case obj
-    when Hash then obj.each { |key, value| yield key.to_sym, value }
-    when Array then obj.each_with_index { |value, index| yield index, value }
+  # The loops below run once per node of the document, so they index by hand:
+  # each_with_index and Integer#times allocate per call.
+  def collect_suffix_matches(obj, end_parts, path, prefix_size, matches)
+    each_child(obj) do |key, value|
+      path.push(key)
+      index = 0
+      while index < end_parts.size
+        parts = end_parts[index]
+        matches[index] << path.dup if path.size >= prefix_size + parts.size && suffix_matches?(path, parts)
+        index += 1
+      end
+      collect_suffix_matches(value, end_parts, path, prefix_size, matches)
+      path.pop
     end
   end
 
-  def max_depth(obj)
+  def suffix_matches?(path, parts)
+    offset = path.size - parts.size
+    index = 0
+    while index < parts.size
+      part = parts[index]
+      return false unless part == :* || part == path[offset + index]
+
+      index += 1
+    end
+    true
+  end
+
+  def each_child(obj)
     case obj
-    when Hash then obj.empty? ? 0 : 1 + obj.each_value.map { |value| max_depth(value) }.max
-    when Array then obj.empty? ? 0 : 1 + obj.map { |value| max_depth(value) }.max
-    else 0
+    when Hash
+      obj.each { |key, value| yield key.to_sym, value }
+    when Array
+      index = 0
+      obj.each do |value|
+        yield index, value
+        index += 1
+      end
     end
   end
 end

data/lib/rspec/openapi/key_transformer.rb

@@ -1,16 +1,17 @@
 # frozen_string_literal: true
 
 class << RSpec::OpenAPI::KeyTransformer = Object.new
+  # The hashes are rebuilt with each rather than to_h, which yields every
+  # entry as a fresh pair array.
   def symbolize(value)
     case value
     when Hash
-      value.to_h do |k, v|
-        if k.to_sym == :examples
-          [k.to_sym, symbolize_examples(v)]
-        else
-          [k.to_sym, symbolize(v)]
-        end
+      result = {}
+      value.each do |k, v|
+        k = k.to_sym
+        result[k] = k == :examples ? symbolize_examples(v) : symbolize(v)
       end
+      result
     when Array
       value.map { |v| symbolize(v) }
     else
@@ -24,17 +25,21 @@ class << RSpec::OpenAPI::KeyTransformer = Object.new
   def symbolize_examples(value)
     return symbolize(value) unless value.is_a?(Hash)
 
-    value.to_h do |k, v|
+    result = {}
+    value.each do |k, v|
       k = k.downcase.tr(' ', '_') unless k.is_a?(Symbol)
 
-      [k.to_sym, symbolize(v)]
+      result[k.to_sym] = symbolize(v)
     end
+    result
   end
 
   def stringify(value)
     case value
     when Hash
-      value.to_h { |k, v| [k.to_s, stringify(v)] }
+      result = {}
+      value.each { |k, v| result[k.to_s] = stringify(v) }
+      result
     when Array
       value.map { |v| stringify(v) }
     else

data/lib/rspec/openapi/nullable_converter.rb

@@ -1,21 +1,22 @@
 # frozen_string_literal: true
 
+require_relative 'hash_helper'
+
 # Converts between the internal `nullable: true` form and the 3.1+ JSON Schema
 # null form (`type: [..., 'null']`). The builder and merger only use `nullable`;
 # normalize! runs on read, to_json_schema! on write.
 class << RSpec::OpenAPI::NullableConverter = Object.new
-  # Keys whose values hold user data, not schemas. Their contents must never be
-  # rewritten, or a recorded example/default that happens to contain a field
-  # named `type` or `nullable` would be silently mangled.
-  DATA_KEYS = [:example, :examples, :default, :enum].freeze
+  NULL_VARIANT = { type: 'null' }.freeze
+  NULLABLE_VARIANT = { nullable: true }.freeze
 
+  # Variants come before their oneOf, so a oneOf sees its variants converted.
   def to_json_schema!(node)
-    each_schema(node) { |schema| nullable_to_type_null!(schema) }
+    RSpec::OpenAPI::HashHelper.each_schema(node) { |schema| nullable_to_type_null!(schema) }
     node
   end
 
   def normalize!(node)
-    each_schema(node) { |schema| type_null_to_nullable!(schema) }
+    RSpec::OpenAPI::HashHelper.each_schema(node) { |schema| type_null_to_nullable!(schema) }
     node
   end
 
@@ -23,15 +24,33 @@ class << RSpec::OpenAPI::NullableConverter = Object.new
 
   def nullable_to_type_null!(schema)
     return unless schema.delete(:nullable)
+    return insert_null_variant!(schema[:oneOf]) if schema[:oneOf] && !schema.key?(:type)
 
     schema[:type] =
       case (type = schema[:type])
       when nil then 'null'
+      when Array then type | ['null']
       else [type, 'null']
       end
   end
 
+  def insert_null_variant!(variants)
+    return if variants.any? { |variant| accepts_null?(variant) }
+
+    index = variants.index { |variant| variant.is_a?(Hash) && variant[:type].to_s > 'null' } || variants.size
+    variants.insert(index, NULL_VARIANT.dup)
+  end
+
+  def accepts_null?(variant)
+    variant.is_a?(Hash) && Array(variant[:type]).include?('null')
+  end
+
+  # A null variant beside a typed oneOf is written back as a variant, so it
+  # stays one. Beside a typeless oneOf it folds into the wrapper, where the
+  # builder and merger keep nullable.
   def type_null_to_nullable!(schema)
+    schema[:nullable] = true if !schema.key?(:type) && schema[:oneOf]&.delete(NULLABLE_VARIANT)
+
     case (type = schema[:type])
     when 'null'
       schema.delete(:type)
@@ -48,17 +67,4 @@ class << RSpec::OpenAPI::NullableConverter = Object.new
       schema[:nullable] = true
     end
   end
-
-  # Yield every schema Hash in the tree, skipping the data subtrees in DATA_KEYS. Each
-  # transform mutates only its own node's keys, so the following each still
-  # iterates a stable Hash.
-  def each_schema(node, &block)
-    case node
-    when Hash
-      yield node
-      node.each { |key, value| each_schema(value, &block) unless DATA_KEYS.include?(key) }
-    when Array
-      node.each { |value| each_schema(value, &block) }
-    end
-  end
 end

data/lib/rspec/openapi/result_recorder.rb

@@ -51,8 +51,9 @@ class RSpec::OpenAPI::ResultRecorder
       RSpec::OpenAPI::OperationConverter.normalize!(spec)
       schema = RSpec::OpenAPI::DefaultSchema.build(title)
       schema[:info].merge!(RSpec::OpenAPI.info)
-      # Normalize the document once here rather than on every merge below.
-      RSpec::OpenAPI::SchemaMerger.merge!(spec, schema)
+      # SchemaFile#read already symbolized the document, so no merge here needs
+      # to normalize it again.
+      RSpec::OpenAPI::SchemaMerger.merge_normalized!(spec, schema)
       new_from_zero = {}
       records.each do |record|
         record_schema = RSpec::OpenAPI::SchemaBuilder.build(record)

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

@@ -4,16 +4,16 @@ class << RSpec::OpenAPI::SchemaBuilder
   # Lookup context threaded through schema building. Bundles the metadata
   # needed to resolve formats, enums, and additionalProperties overrides for
   # a value at a given path under a record's request/response side.
-  BuildContext = Struct.new(:record, :context, :path, :key, keyword_init: true) do
+  #
+  # 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
     def descend(child_key)
-      self.class.new(
-        record: record, context: context, key: child_key,
-        path: path ? "#{path}.#{child_key}" : child_key.to_s,
-      )
+      self.class.new(record, context, path ? "#{path}.#{child_key}" : child_key.to_s, child_key)
     end
 
     def for_array_items
-      self.class.new(record: record, context: context, path: path, key: nil)
+      self.class.new(record, context, path, nil)
     end
   end
   private_constant :BuildContext

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

@@ -12,7 +12,7 @@ class << RSpec::OpenAPI::SchemaBuilder
       # Drop empty `{}` schemas (e.g. items of an empty array) — they carry no
       # type info and would otherwise spuriously mark every property of their
       # populated siblings as nullable via the missing-key nullable rule.
-      non_empty = variations.reject(&:empty?)
+      non_empty = widen_integers(variations.reject(&:empty?))
       return {} if non_empty.empty?
       return non_empty.first if non_empty.size == 1
 
@@ -57,11 +57,15 @@ class << RSpec::OpenAPI::SchemaBuilder
     private
 
     def merge_object_variations(variations)
-      {
-        type: 'object',
-        properties: merge_property_variations(variations, allow_recursive_merge: true),
-        required: variations.map { |v| v[:required] || [] }.reduce(:&) || [],
-      }
+      merged = { type: 'object' }
+      if variations.any? { |v| v.key?(:properties) }
+        merged[:properties] = merge_property_variations(variations, allow_recursive_merge: true)
+        merged[:required] = variations.map { |v| v[:required] || [] }.reduce(:&) || []
+      end
+      # Every variation sits at one path, so they all carry the same override.
+      additional = variations.find { |v| v.key?(:additionalProperties) }
+      merged[:additionalProperties] = additional[:additionalProperties] if additional
+      merged
     end
 
     # Merge multiple array schemas by merging their `items` schemas.
@@ -112,6 +116,7 @@ class << RSpec::OpenAPI::SchemaBuilder
     def merge_multi(prop_variations)
       return { oneOf: flatten_one_of(prop_variations) } if prop_variations.any? { |p| p.key?(:oneOf) }
 
+      prop_variations = widen_integers(prop_variations)
       prop_types = prop_variations.map { |p| p[:type] }.compact.uniq
       return one_of_schema(prop_variations) if prop_types.size > 1
 
@@ -122,15 +127,23 @@ class << RSpec::OpenAPI::SchemaBuilder
       end
     end
 
+    # Every integer is a number, so integers seen beside numbers are numbers.
+    def widen_integers(variations)
+      return variations unless variations.any? { |v| v[:type] == 'number' }
+
+      variations.reject { |v| v[:type] == 'integer' }
+    end
+
     def flatten_one_of(prop_variations)
-      prop_variations.each_with_object([]) do |prop, options|
+      options = prop_variations.each_with_object([]) do |prop, acc|
         clean = without_nullable(prop)
         if clean.key?(:oneOf)
-          options.concat(clean[:oneOf])
+          acc.concat(clean[:oneOf])
         elsif !clean.empty?
-          options << clean
+          acc << clean
         end
-      end.uniq
+      end
+      sort_by_type(options.uniq)
     end
 
     def without_nullable(prop)
@@ -138,7 +151,13 @@ class << RSpec::OpenAPI::SchemaBuilder
     end
 
     def one_of_schema(variations)
-      { oneOf: variations.map { |p| without_nullable(p) }.uniq }
+      { oneOf: sort_by_type(variations.map { |p| without_nullable(p) }.uniq) }
+    end
+
+    # The same order the merger keeps, so the document does not depend on which
+    # example ran first.
+    def sort_by_type(options)
+      options.sort_by.with_index { |option, index| [option[:type].to_s, index] }
     end
   end
 

data/lib/rspec/openapi/schema_builder.rb

@@ -5,6 +5,17 @@ require_relative 'schema_builder/build_context'
 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
+  OVERRIDE_MEMBERS = {
+    additional_properties: {
+      request: :request_additional_properties, response: :response_additional_properties,
+    },
+    hybrid_additional_properties: {
+      request: :request_hybrid_additional_properties, response: :response_hybrid_additional_properties,
+    },
+  }.freeze
+
   # @param [RSpec::OpenAPI::Record] record
   # @return [Hash]
   def build(record)
@@ -56,7 +67,7 @@ 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: record, context: :response)
+    ctx = BuildContext.new(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)
@@ -141,7 +152,7 @@ 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: record, context: :request, key: key, path: key.to_s)
+    ctx = BuildContext.new(record, :request, key.to_s, key)
     {
       name: key.to_s,
       in: location,
@@ -153,7 +164,7 @@ class << RSpec::OpenAPI::SchemaBuilder
 
   def build_response_headers(record)
     record.response_headers.to_h do |key, value|
-      ctx = BuildContext.new(record: record, context: :response, key: key, path: key.to_s)
+      ctx = BuildContext.new(record, :response, key.to_s, key)
       [key, { schema: build_property(try_cast(value), ctx) }]
     end
   end
@@ -175,7 +186,7 @@ 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: record, context: :request)
+    ctx = BuildContext.new(record, :request)
     schema = build_property(record.request_params, ctx)
     example = example_enabled?(record) ? build_example(record.request_params) : nil
 
@@ -207,10 +218,10 @@ class << RSpec::OpenAPI::SchemaBuilder
       return
     end
 
-    property[:properties] = value.to_h do |k, v|
-      [k, build_property(v, ctx.descend(k))]
-    end
-    property[:required] = property[:properties].keys
+    properties = {}
+    value.each { |k, v| properties[k] = build_property(v, ctx.descend(k)) }
+    property[:properties] = properties
+    property[:required] = properties.keys
     apply_additional_properties(property, override,
                                 infer_override(ctx.path, ctx.record, ctx.context, :hybrid_additional_properties),)
   end
@@ -259,7 +270,7 @@ class << RSpec::OpenAPI::SchemaBuilder
     return nil if !path || !record
 
     # Keys are already normalized to strings by SharedExtractor.normalize_enum
-    record.send("#{context}_enum")&.[](path.to_s)
+    record[ENUM_MEMBERS.fetch(context)]&.[](path.to_s)
   end
 
   # Looks up an override for the current path under one of the per-context
@@ -268,7 +279,7 @@ class << RSpec::OpenAPI::SchemaBuilder
   # distinguishable from "no override"; for :hybrid_additional_properties
   # plain lookup is enough because only Hash values are meaningful.
   def infer_override(path, record, context, kind)
-    overrides = record.send("#{context}_#{kind}")
+    overrides = record[OVERRIDE_MEMBERS.fetch(kind).fetch(context)]
     return nil unless overrides
 
     # path is nil at the body root; nil.to_s == '' lets users target it via { '' => ... }.
@@ -282,9 +293,7 @@ class << RSpec::OpenAPI::SchemaBuilder
     return true if value == 'true'
     return false if value == 'false'
 
-    Integer(value)
-  rescue TypeError, ArgumentError
-    value
+    Integer(value, exception: false) || value
   end
 
   def build_example(value)

data/lib/rspec/openapi/schema_cleaner.rb

@@ -13,6 +13,7 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
   def cleanup_components_schemas!(base, spec)
     cleanup_hash!(base, spec, 'components.schemas.*')
     cleanup_hash!(base, spec, 'components.schemas.*.properties.*')
+    cleanup_one_of_properties!(base, spec, 'components.schemas.*')
   end
 
   # Cleanup specific elements that exists in the base but not in the spec
@@ -39,6 +40,10 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
     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 temporary fields used for internal processing
     cleanup_temporary_fields!(base)
 
@@ -50,35 +55,36 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
 
     return if security_schemes.empty?
 
-    paths_to_security_definitions = RSpec::OpenAPI::HashHelper.matched_paths_deeply_nested(base, 'paths', 'security')
-
-    paths_to_security_definitions.each do |path|
-      parent_path_definition = base.dig(*path.take(path.length - 1))
-
+    each_operation(base) do |operation|
       security_schemes.each do |security_scheme_name, security_scheme|
-        remove_parameters_conflicting_with_security_scheme!(
-          parent_path_definition, security_scheme, security_scheme_name,
-        )
+        remove_parameters_conflicting_with_security_scheme!(operation, security_scheme, security_scheme_name)
       end
     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)
-    paths_to_objects = [
-      *RSpec::OpenAPI::HashHelper.matched_paths_deeply_nested(base, 'components.schemas', 'properties'),
-      *RSpec::OpenAPI::HashHelper.matched_paths_deeply_nested(base, 'paths', 'properties'),
-    ]
-    paths_to_objects.each do |path|
-      parent = base.dig(*path.take(path.length - 1))
-      next unless parent
-
-      # "required" array  must not be present if empty
-      parent.delete(:required) if parent[:required] && parent[:required].empty?
+    [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
     end
   end
 
   private
 
+  # 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)
+    base[:paths].each_value do |path_item|
+      next unless path_item.is_a?(Hash)
+
+      path_item.each_value { |operation| yield operation if operation.is_a?(Hash) }
+    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)
@@ -113,25 +119,48 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
   end
 
   def cleanup_array!(base, spec, selector, fields_for_identity)
-    marshal = lambda do |obj|
-      Marshal.dump(obj.slice(*fields_for_identity))
-    end
+    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)
       next unless target_array.is_a?(Array) && spec_array.is_a?(Array)
 
-      spec_identities = Set.new(spec_array.map(&marshal))
-      target_array.select! { |e| spec_identities.include?(marshal.call(e)) }
-      target_array.sort_by! { |param| fields_for_identity.map { |f| param[f] }.join('-') }
+      spec_identities = Set.new(spec_array.map(&identity))
+      target_array.select! { |e| spec_identities.include?(identity.call(e)) }
+      target_array.sort_by! { |param| identity.call(param).join('-') }
       # Keep the last duplicate to produce the result stably
-      deduplicated = target_array.reverse.uniq { |param| param.slice(*fields_for_identity) }.reverse
+      deduplicated = target_array.reverse.uniq(&identity).reverse
       target_array.replace(deduplicated)
     end
     base
   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)
+
+      variants.each { |variant| cleanup_variant_properties!(variant, variants, fresh) }
+    end
+    base
+  end
+
+  # Variants are matched by type, since the spec may hold one of them as a bare
+  # schema or in another order. Two variants of one type can not be told apart
+  # that way, so those stay as they are, like a variant of a type the spec does
+  # not hold.
+  def cleanup_variant_properties!(variant, variants, fresh)
+    return unless variant.is_a?(Hash) && variant[:properties].is_a?(Hash)
+    return unless variants.one? { |other| other.is_a?(Hash) && other[:type] == variant[:type] }
+
+    counterpart = RSpec::OpenAPI::HashHelper.variant_of_type(fresh, variant[:type])
+    return unless counterpart
+
+    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.
   def cleanup_hash!(base, spec, selector)

data/lib/rspec/openapi/schema_merger.rb

@@ -25,7 +25,13 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
     merge_schema!(base, RSpec::OpenAPI::KeyTransformer.symbolize(spec))
   end
 
-  SIMILARITY_THRESHOLD = 0.5
+  SCHEMA_KEYS = [:schema, :schemas, :itemSchema].freeze
+  DATA_KEYS = [:example, :examples, :default, :enum].freeze
+  NUMERIC_TYPES = ['integer', 'number'].freeze
+  ANNOTATION_KEYS = [
+    :title, :description, :deprecated, :readOnly, :writeOnly, :example, :examples, :default, :externalDocs, :xml,
+    :discriminator,
+  ].freeze
 
   private
 
@@ -34,19 +40,46 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
   # may be an array whose Hash elements have a key name.
   #
   # TODO: Should we probably force-merge `summary` regardless of manual modifications?
-  def merge_schema!(base, spec)
-    if (options = base[:oneOf])
-      merge_closest_match!(options, spec)
-
-      return base
-    end
+  def merge_schema!(base, spec, in_schema: false)
+    return merge_one_of!(base, spec) if base[:oneOf]
 
     prune_stale_object_fields!(base, spec)
+    spec = widen_to_number!(base, spec) if in_schema
 
-    spec.each { |key, value| merge_entry!(base, key, value) }
+    spec.each { |key, value| merge_schema_entry!(base, key, value, in_schema) }
     base
   end
 
+  # Every integer is a number, so a value seen as both is a number. The format
+  # of the integer side would be wrong on a number, so only the number's stays.
+  def widen_to_number!(base, spec)
+    return spec if base[:type] == spec[:type] || !same_type?(base[:type], spec[:type])
+    return spec.reject { |key, _| [:type, :format].include?(key) } if base[:type] == 'number'
+
+    base.delete(:format)
+    spec
+  end
+
+  def merge_schema_entry!(base, key, value, in_schema)
+    if in_schema && key == :properties && base[key].is_a?(Hash) && value.is_a?(Hash)
+      value.each { |name, property| merge_entry!(base[key], name, property, true) }
+    elsif DATA_KEYS.include?(key)
+      merge_data!(base, key, value)
+    else
+      merge_entry!(base, key, value, in_schema || SCHEMA_KEYS.include?(key))
+    end
+  end
+
+  # Recorded data stays data however it is shaped, so a field named like a
+  # schema key never gets merged as one.
+  def merge_data!(base, key, value)
+    if base[key].is_a?(Hash) && value.is_a?(Hash)
+      value.each { |name, item| merge_data!(base[key], name, item) }
+    else
+      base[key] = value
+    end
+  end
+
   # When the new spec converts an object to a dictionary (introduces
   # `additionalProperties` on a node that previously had `properties` /
   # `required`), drop the stale fields so the merged result reflects the
@@ -60,9 +93,9 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
     base.delete(:required)
   end
 
-  def merge_entry!(base, key, value)
+  def merge_entry!(base, key, value, in_schema)
     if base[key].is_a?(Hash) && value.is_a?(Hash)
-      merge_hash_entry!(base, key, value)
+      merge_hash_entry!(base, key, value, in_schema)
     elsif base[key].is_a?(Array) && value.is_a?(Array)
       # parameters need to be merged as if `name` and `in` were the Hash keys.
       merge_arrays(base, key, value)
@@ -71,18 +104,62 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
     end
   end
 
-  def merge_hash_entry!(base, key, value)
+  def merge_hash_entry!(base, key, value, in_schema)
     # Handle example/examples conflict - convert to examples when mixed
     normalize_example_fields!(base[key], value)
 
-    # If the new value has oneOf, replace the entire value instead of merging
-    if value.key?(:oneOf)
+    if in_schema && one_of_needed?(base[key], value)
+      merge_one_of!(base[key], value)
+    elsif value.key?(:oneOf)
       base[key] = value
     elsif !base[key].key?(:$ref)
-      merge_schema!(base[key], value)
+      merge_schema!(base[key], value, in_schema: in_schema)
     end
   end
 
+  def one_of_needed?(base, spec)
+    return false if base.key?(:$ref)
+
+    spec.key?(:oneOf) || conflicting_types?(base, spec)
+  end
+
+  def conflicting_types?(base, spec)
+    base[:type].is_a?(String) && spec[:type].is_a?(String) && !same_type?(base[:type], spec[:type])
+  end
+
+  def same_type?(first, second)
+    first == second || (NUMERIC_TYPES.include?(first) && NUMERIC_TYPES.include?(second))
+  end
+
+  def merge_one_of!(base, spec)
+    nullable = base.delete(:nullable) || spec[:nullable]
+    wrap_in_one_of!(base) unless base[:oneOf]
+
+    one_of_variants(spec).each { |variant| merge_variant!(base, variant) }
+    base[:nullable] = true if nullable
+    base
+  end
+
+  # Annotations describe the whole value, so they stay beside the oneOf. A schema
+  # without a type constrains every variant too, and a variant made of it would
+  # match every other type, so all of it stays beside the oneOf.
+  def wrap_in_one_of!(base)
+    # A hand-written `oneOf:` left empty reads back as nil.
+    base.delete(:oneOf)
+    variant = base[:type] ? base.reject { |key, _| annotation?(key) } : {}
+    rest = base.reject { |key, _| variant.key?(key) }
+    base.replace({ oneOf: [variant].reject(&:empty?) }.merge(rest))
+  end
+
+  def annotation?(key)
+    ANNOTATION_KEYS.include?(key) || key.start_with?('x-')
+  end
+
+  def one_of_variants(schema)
+    variants = schema[:oneOf] || [schema.reject { |key, _| key == :nullable }]
+    variants.reject { |variant| variant.is_a?(Hash) && variant.empty? }
+  end
+
   # do not ADD `properties` or `required` fields if `additionalProperties` field is present
   def skip_due_to_additional_properties?(base, key)
     base.key?(:additionalProperties) && [:properties, :required].include?(key)
@@ -132,16 +209,8 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
   end
 
   def merge_parameter_with_schema(base_param, new_param)
-    base_schema = base_param[:schema]
-    new_schema = new_param[:schema]
-
-    # If schemas have different types, create a oneOf
-    merged = if base_schema && new_schema && schemas_have_different_types?(base_schema, new_schema)
-               merged_schema = merge_schemas_into_one_of(base_schema, new_schema)
-               base_param.merge(new_param).merge(schema: merged_schema)
-             else
-               base_param.merge(new_param)
-             end
+    merge_entry!(base_param, :schema, new_param[:schema], true)
+    merged = base_param.merge(new_param.reject { |key, _| key == :schema })
 
     # Once a parameter has been seen missing in any earlier test case, keep it optional
     # even if later test cases mark it required again.
@@ -150,37 +219,6 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
     merged
   end
 
-  def schemas_have_different_types?(schema1, schema2)
-    # If either already has oneOf, we need to merge into it
-    return true if schema1[:oneOf] || schema2[:oneOf]
-
-    type1 = schema1[:type]
-    type2 = schema2[:type]
-
-    type1 && type2 && type1 != type2
-  end
-
-  def merge_schemas_into_one_of(base_schema, new_schema)
-    existing_types = extract_schema_types(base_schema)
-    new_types = extract_schema_types(new_schema)
-
-    all_types = existing_types + new_types
-    all_types.uniq!
-
-    # If only one type remains, return it directly
-    return all_types.first if all_types.size == 1
-
-    { oneOf: all_types }
-  end
-
-  def extract_schema_types(schema)
-    if schema[:oneOf]
-      schema[:oneOf].map { |s| s.reject { |k, _| k == :example } }
-    else
-      [schema.reject { |k, _| k == :example }]
-    end
-  end
-
   def index_parameters_by_identity(parameters)
     parameters.to_h { |p| [[p[:name], p[:in]], p] }
   end
@@ -209,20 +247,39 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
     hash[:examples] = { name => example }
   end
 
-  def merge_closest_match!(options, spec)
-    score, option = options.map { |option| [similarity(option, spec), option] }.max_by(&:first)
+  def merge_variant!(base, spec)
+    options = base[:oneOf]
+    return if spec[:oneOf] || options.include?(spec)
+    return if options.any? { |option| option.is_a?(Hash) && option.key?(:$ref) }
 
-    return if option&.key?(:$ref)
-
-    return if spec[:oneOf]
-
-    if score.to_f > SIMILARITY_THRESHOLD
-      merge_schema!(option, spec)
+    option = matching_option(base, spec)
+    if option
+      merge_schema!(option, spec, in_schema: true)
     else
       options.push(spec)
+      sort_by_type!(options)
     end
   end
 
+  # A value could match two variants of one type, so those merge into one, the
+  # closest when there are several. A discriminator tells the variants apart by
+  # a property, so only the variants that declare it are candidates there.
+  def matching_option(base, spec)
+    candidates = base[:oneOf].select { |option| option.is_a?(Hash) && same_type?(option[:type], spec[:type]) }
+    if (property = base.dig(:discriminator, :propertyName))
+      candidates.select! { |option| option.dig(:properties, property.to_sym) }
+    end
+    candidates.max_by { |option| similarity(option, spec) }
+  end
+
+  def sort_by_type!(options)
+    options.replace(options.sort_by.with_index { |option, index| [type_name(option), index] })
+  end
+
+  def type_name(schema)
+    schema.is_a?(Hash) ? schema[:type].to_s : ''
+  end
+
   def similarity(first, second)
     return 1 if first == second
 
@@ -231,7 +288,7 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
       when [Array, Array]
         (first & second).size / [first.size, second.size].max.to_f
       when [Hash, Hash]
-        return 1 if first.merge(second).key?(:$ref)
+        return 1 if first.key?(:$ref) || second.key?(:$ref)
 
         intersection = first.keys & second.keys
         total_size = [first.size, second.size].max.to_f

data/lib/rspec/openapi/schema_sorter.rb

@@ -37,8 +37,9 @@ class << RSpec::OpenAPI::SchemaSorter = Object.new
     end
   end
 
+  # Re-inserting a key moves it to the end, so re-inserting every key in sorted
+  # order sorts the hash in place.
   def deep_sort_hash!(hash)
-    sorted = hash.entries.sort_by { |k, _| k.to_s }.to_h.transform_keys(&:to_sym)
-    hash.replace(sorted)
+    hash.keys.sort_by(&:to_s).each { |key| hash[key.to_sym] = hash.delete(key) }
   end
 end

data/lib/rspec/openapi/version.rb

@@ -2,6 +2,6 @@
 
 module RSpec
   module OpenAPI
-    VERSION = '0.33.1'
+    VERSION = '0.35.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-openapi
 version: !ruby/object:Gem::Version
-  version: 0.33.1
+  version: 0.35.0
 platform: ruby
 authors:
 - Takashi Kokubun
@@ -99,7 +99,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/exoego/rspec-openapi
   source_code_uri: https://github.com/exoego/rspec-openapi
-  changelog_uri: https://github.com/exoego/rspec-openapi/releases/tag/v0.33.1
+  changelog_uri: https://github.com/exoego/rspec-openapi/releases/tag/v0.35.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -115,7 +115,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Generate OpenAPI schema from RSpec request specs
 test_files: []