rspec-openapi 0.34.0 → 0.36.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d493f4696b8bf07c0dcdfe1cbfb4d06736ac7b7efc3c103b8692f6d7aab01db7
-  data.tar.gz: 38e4d7f3268a4d84e60ad6f047c3176b1d161ef895f5648422d7231e34ccfff5
+  metadata.gz: a9ca3c8b1eadd4f1b45f1a3c6fcfe533ac85e2eb836ff2dd849fec8f22f7a42d
+  data.tar.gz: 43ef531b0a5141c1d95e075fda5a5020b0c1792c73f4df686ce152801e7c29e7
 SHA512:
-  metadata.gz: c1dbea1b90c265e2e636a77f406456c2e871fdefa476845538cd44d4486887e09298ce3e55406cb1e2f0c9305a030328a1300638a9804753c56d3b56b40e96cb
-  data.tar.gz: 597cf318feef44fa58393dc94c3f4101d990e755028df0df16f76024aa6d79baff86a6d689b5f968c792a8e86e695ddd8f7abfdf89b2c314c9d4c381b83a4309
+  metadata.gz: 81ce9e7146b012243391d4c15b19e18d836350aec0a7547ad8d8d629acfa424b35ec7a467b32f033f812bc88cc8ceea4b740cf13703180ee6e7054ea6e4993da
+  data.tar.gz: a3312e057a52f28090989a26c701aab02b0b5850270d73e04e30b963dfcb5e0bb612a48c2b2fcca275ebfebdbb9df52e87378d35675336ccd71a5af920a02709

data/README.md

@@ -228,6 +228,10 @@ RSpec::OpenAPI.tags_builder = -> (example) { example.metadata.dig(:example_group
 # This example assigns 'date-time' format to properties with names ending in '_at'
 RSpec::OpenAPI.formats_builder = ->(_example, key) { key.end_with?('_at') ? 'date-time' : nil }
 
+# Mark server-assigned properties as `readOnly`. Off by default.
+# A builder of your own gets the RSpec example and a property name. See "Can I mark `id` and timestamps as `readOnly`?" below.
+RSpec::OpenAPI.read_only_builder = RSpec::OpenAPI::DEFAULT_READ_ONLY_BUILDER
+
 # Change the example type(s) that will generate schema
 RSpec::OpenAPI.example_types = %i[request]
 
@@ -242,6 +246,10 @@ RSpec::OpenAPI.ignored_path_params = %i[controller action format]
 # String or Regexp is acceptable.
 RSpec::OpenAPI.ignored_paths = ["/admin/full/path/", Regexp.new("^/_internal/")]
 
+# Whether a run adds and updates without removing anything. `nil` (default) lets each run decide,
+# see "Can I run a subset of specs?" below. `true` or `false` forces it, as does `OPENAPI_PARTIAL_UPDATE=1` or `=0`.
+RSpec::OpenAPI.partial_update = nil
+
 # Your custom post-processing hook (like unrandomizing IDs)
 RSpec::OpenAPI.post_process_hook = -> (path, records, spec) do
   RSpec::OpenAPI::HashHelper.matched_paths(spec, 'paths.*.*.responses.*.content.*.*.*.id').each do |paths|
@@ -396,11 +404,66 @@ components:
 Note that automatic `schemas` update feature is still new and may not work in complex scenario.
 If you find a room for improvement, open an issue.
 
+### Can I mark `id` and timestamps as `readOnly`?
+
+Yes, with `read_only_builder`. It is off by default.
+
+```rb
+RSpec::OpenAPI.read_only_builder = RSpec::OpenAPI::DEFAULT_READ_ONLY_BUILDER
+```
+
+`DEFAULT_READ_ONLY_BUILDER` picks the names in `DEFAULT_READ_ONLY_KEYS`: `id`, `uuid`, `created_at`
+and `updated_at`. Foreign keys such as `user_id` are not in it, since clients usually send them. A
+builder of your own gets the RSpec example and a property name, and may return `true` for any name.
+The names can also be listed per example, as whole names or patterns.
+
+```rb
+describe 'GET /posts', openapi: { read_only: ['id', /_count\z/] } do
+  # `read_only: false` turns it off for an example, and `read_only: true` hands it back to the builder.
+end
+```
+
+A property the builder picks gets `readOnly: true` in response schemas. Keep in mind what that
+means. A client should not send the property (OpenAPI 3.0), or the server may ignore or reject it
+(3.1 and later). So a request that sends the property says the opposite, and the request wins.
+That holds under `read_only: false` too, which only stops an example from marking.
+In a schema shared by a request and a response through `$ref`, the component then keeps
+`readOnly: false`. That explicit `false` lets partial runs (see "Can I run a subset of specs?"
+below), such as `parallel_tests` workers, agree whichever order they run in. A full run decides
+it anew. Inline request schemas never carry `readOnly`.
+
 ### How can I add information which can't be generated from RSpec?
 
 rspec-openapi tries to preserve manual modifications as much as possible when generating specs.
 You can directly edit `doc/openapi.yaml` as you like without spoiling the automatic generation capability.
 
+### Can I run a subset of specs?
+
+Yes. A run over part of the suite adds and updates what it records and removes nothing.
+It prints a notice when it updates the file this way.
+
+```bash
+$ OPENAPI=1 bundle exec rspec spec/requests/tables_spec.rb
+```
+
+A run counts as partial in two cases.
+
+- The examples are narrowed, by `-e`, `--tag`, a line number, `--only-failures` or a leftover `fit`.
+  An exclusion such as `--tag ~slow` does not count.
+- A spec file next to one that recorded a request was left out. So `rspec spec/requests/tables_spec.rb`
+  is partial, while `rspec spec/requests` and `rspec spec/requests/*_spec.rb` are not.
+
+Every other run also removes the paths, operations, parameters and properties it did not record.
+This is how removed endpoints disappear from the file, so run all specs for that.
+
+A `parallel_tests` worker sees only part of the files, so it never removes anything, whichever files it got.
+rspec-openapi knows a worker by the `TEST_ENV_NUMBER` variable that `parallel_tests` sets.
+Run the suite in one process when stale entries should go.
+
+Set `RSpec::OpenAPI.partial_update` to `true` or `false`, or `OPENAPI_PARTIAL_UPDATE=1` or `=0`, to force one mode.
+Minitest has no run information to decide from. It removes nothing in a `parallel_tests` worker or when the
+option is `true`, and removes stale entries otherwise.
+
 ### Can I exclude specific specs from OpenAPI generation?
 
 Yes, you can specify `openapi: false` to disable the automatic generation.
@@ -419,6 +482,44 @@ RSpec.describe '/resources', type: :request do
 end
 ```
 
+### How can I keep the generated file stable across runs?
+
+rspec-openapi sorts `paths`, HTTP methods, response status codes, content types and the names of `examples`.
+So the structure of the file does not depend on the order in which RSpec runs your tests.
+
+The values inside `example` are different. They are copied from the real requests and responses
+in your tests. Anything random in your app or test data shows up as a diff on every run.
+Common sources are Faker, `SecureRandom`, `Time.now` and auto-increment IDs.
+
+One option is to make the values stable in your test setup. This is plain RSpec configuration
+and is not specific to rspec-openapi. For example:
+
+```rb
+if ENV['OPENAPI']
+  seed = ENV.fetch('OPENAPI_SEED', 1234).to_i
+  srand(seed)
+  Faker::Config.random = Random.new(seed) if defined?(Faker)
+
+  RSpec.configure do |config|
+    config.include ActiveSupport::Testing::TimeHelpers
+
+    config.around do |example|
+      travel_to(Time.zone.local(2024, 1, 1, 12, 0, 0)) { example.run }
+    end
+  end
+end
+```
+
+The other option is to keep the random values out of the file. Set `RSpec::OpenAPI.enable_example = false`
+to drop `example` everywhere, use `example_mode: :none` on the noisy tests only, or rewrite the values
+in `RSpec::OpenAPI.post_process_hook`. See [Configuration](#configuration) for both.
+
+One more thing to know. When several tests hit the same endpoint in the default `:single` mode,
+the `example` comes from the test that ran last. With `config.order = :random` the winner changes
+from run to run. Run with `--order defined` while generating the file, or switch those tests to
+`example_mode: :multiple` so that each test writes its own named example.
+See [Multiple Examples Mode](#multiple-examples-mode).
+
 ## Customizations
 
 Some examples' attributes can be overwritten via RSpec metadata options. Example:

data/lib/rspec/openapi/components_updater.rb

@@ -7,7 +7,8 @@ class << RSpec::OpenAPI::ComponentsUpdater = Object.new
 
   # @param [Hash] base
   # @param [Hash] fresh
-  def update!(base, fresh)
+  # @param [Boolean] partial add to the schemas without removing anything
+  def update!(base, fresh, partial: false)
     # Top-level schema: Used as the body of request or response
     top_level_refs = paths_to_top_level_refs(base)
     fresh_schemas = build_fresh_schemas(top_level_refs, base, fresh)
@@ -22,8 +23,9 @@ class << RSpec::OpenAPI::ComponentsUpdater = Object.new
 
     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 } })
+    fresh_components = { components: { schemas: fresh_schemas } }
+    RSpec::OpenAPI::SchemaMerger.merge_normalized!(base, fresh_components)
+    RSpec::OpenAPI::SchemaCleaner.cleanup_components_schemas!(base, fresh_components) unless partial
   end
 
   private
@@ -52,37 +54,65 @@ class << RSpec::OpenAPI::ComponentsUpdater = Object.new
   # 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 = fresh.dig(*paths[0..-2])
+      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
 
+  # 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)).to_sym
-    fresh_schemas[schema_name] ||= {}
-    RSpec::OpenAPI::SchemaMerger.merge_normalized!(fresh_schemas[schema_name], 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))
+      # Nothing was recorded for this body, so there is nothing to fill the
+      # schema from. A partial run leaves such operations in base, and so does
+      # a status code no example produces any more.
+      next if schema_body.nil?
 
-      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
+
+  # The paths come from matched_paths, so their segments are symbols and the
+  # indexes of oneOf variants. A path to a media type ends in the content
+  # type, one to a variant in its index under the oneOf of the schema.
   def dig_schema(obj, paths)
-    # Response code can be an integer
-    paths = paths.map { |path| path.is_a?(Integer) ? path : path.to_sym }
-    item_schema = obj.dig(*paths, :schema, :items)
-    object_schema = obj.dig(*paths, :schema)
-    one_of_schema = obj.dig(*paths.take(paths.size - 1), :schema, :oneOf, paths.last)
+    media_type = obj.dig(*paths)
+    return obj.dig(*paths[0...-1], :schema, :oneOf, paths.last) unless media_type.is_a?(Hash)
 
-    item_schema || object_schema || one_of_schema
+    schema = media_type[:schema]
+    (schema.is_a?(Hash) && schema[:items]) || schema
   end
 
   def paths_to_top_level_refs(base)
@@ -97,11 +127,9 @@ 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
 
@@ -113,10 +141,7 @@ class << RSpec::OpenAPI::ComponentsUpdater = Object.new
       'paths.*.*.responses.*.content.application/json.schema',
     ]
     nested_refs = roots.flat_map do |root|
-      [
-        *RSpec::OpenAPI::HashHelper.matched_paths_deeply_nested(base, root, 'properties.*.$ref'),
-        *RSpec::OpenAPI::HashHelper.matched_paths_deeply_nested(base, root, 'properties.*.items.$ref'),
-      ]
+      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

data/lib/rspec/openapi/extractors/shared_extractor.rb

@@ -20,7 +20,6 @@ class SharedExtractor
 
   def self.attributes(example)
     metadata = merge_openapi_metadata(example.metadata)
-    request_example_mode, response_example_mode = normalize_example_mode(metadata[:example_mode], example)
     response_additional_properties, request_additional_properties = resolve_additional_properties(metadata)
     response_hybrid_additional_properties, request_hybrid_additional_properties =
       resolve_hybrid_additional_properties(metadata)
@@ -31,13 +30,13 @@ class SharedExtractor
       summary: metadata[:summary] || RSpec::OpenAPI.summary_builder.call(example),
       tags: metadata[:tags] || RSpec::OpenAPI.tags_builder.call(example),
       formats: metadata[:formats] || RSpec::OpenAPI.formats_builder.curry.call(example),
+      **read_only_lookups(metadata, example),
       operation_id: metadata[:operation_id],
       required_request_params: metadata[:required_request_params] || [],
       security: metadata[:security],
       description: metadata[:description] || RSpec::OpenAPI.description_builder.call(example),
       deprecated: metadata[:deprecated],
-      request_example_mode: request_example_mode,
-      response_example_mode: response_example_mode,
+      **example_modes(metadata, example),
       example_key: resolve_example_key(metadata, example),
       example_name: metadata[:example_name] || RSpec::OpenAPI.example_name_builder.call(example),
       response_enum: normalize_enum(metadata[:response_enum]) || base_enum,
@@ -71,6 +70,40 @@ class SharedExtractor
     [response, request]
   end
 
+  def self.example_modes(metadata, example)
+    request_example_mode, response_example_mode = normalize_example_mode(metadata[:example_mode], example)
+    { request_example_mode: request_example_mode, response_example_mode: response_example_mode }
+  end
+
+  # The metadata wins over the builder for what a response marks. `false` marks
+  # nothing, and `true` hands it back to the builder, for a group that turned it
+  # off. A request that sends a property is evidence whatever its example
+  # marks, so its side takes the builder's candidates as well.
+  def self.read_only_lookups(metadata, example)
+    builder = RSpec::OpenAPI.read_only_builder&.curry&.call(example)
+    value = metadata.fetch(:read_only, true)
+    return { response_read_only: builder, request_read_only: builder } if value == true
+
+    listed = normalize_read_only(value, example)
+    request = listed && builder ? ->(key) { listed[key] || builder[key] } : listed || builder
+    { response_read_only: listed, request_read_only: request }
+  end
+
+  READ_ONLY_PATTERN_CLASSES = [String, Symbol, Regexp].freeze
+
+  def self.normalize_read_only(value, example)
+    return nil unless value
+
+    patterns = Array(value)
+    unless patterns.all? { |pattern| READ_ONLY_PATTERN_CLASSES.any? { |klass| pattern.is_a?(klass) } }
+      raise ArgumentError, 'read_only must be true, false, or property names as Strings, Symbols or Regexps, ' \
+                           "got #{value.inspect}#{example_context(example)}"
+    end
+
+    patterns = patterns.map { |pattern| pattern.is_a?(Regexp) ? pattern : pattern.to_s }
+    ->(key) { patterns.any? { |pattern| pattern.is_a?(Regexp) ? pattern.match?(key) : pattern == key } }
+  end
+
   def self.normalize_enum(enum_hash)
     return nil if enum_hash.nil? || enum_hash.empty?
 
@@ -153,9 +186,12 @@ class SharedExtractor
   end
 
   def self.example_mode_error(value, example)
-    context = example&.full_description
-    context = " (example: #{context})" if context
     "example_mode must be a Symbol/String in #{VALID_EXAMPLE_MODES.inspect} " \
-      "or a Hash with :request/:response keys, got #{value.inspect}#{context}"
+      "or a Hash with :request/:response keys, got #{value.inspect}#{example_context(example)}"
+  end
+
+  def self.example_context(example)
+    context = example&.full_description
+    context ? " (example: #{context})" : ''
   end
 end

data/lib/rspec/openapi/hash_helper.rb

@@ -7,56 +7,160 @@ 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('.')
+  # Yields each match of selector in obj as its parent, the matching key and
+  # the value, with the value at the same path in other (nil when other has
+  # none). Callers that only edit the matched nodes, or compare them with a
+  # fresh document, get them without a path to dig back up from the root for
+  # every match.
+  def each_matched(obj, other, selector, &block)
+    walk_matched(obj, other, split_selector(selector), 0, &block)
+  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?
+  # 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
 
-      matched_paths(obj, "#{begin_selector}.#{'*.' * gap}#{end_selector}")
+  # 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
+
+  # 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
+
+  # The selectors are a fixed set of literals, some of them matched once per
+  # media type of the document, so each is split once.
+  SELECTOR_PARTS = Hash.new { |cache, selector| cache[selector] = selector.split('.').map(&:to_sym).freeze }
+  private_constant :SELECTOR_PARTS
+
   private
 
-  def collect_matches(obj, selector_parts, depth, prefix, matches)
+  def split_selector(selector)
+    SELECTOR_PARTS[selector]
+  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)
+  def walk_matched(obj, other, selector_parts, depth, &block)
+    part = selector_parts[depth]
+    last = depth == selector_parts.size - 1
+
+    each_child(obj) do |key, value|
+      next unless part == :* || part == key
+
+      if last
+        yield obj, key, value, child_of(other, key)
+      else
+        walk_matched(value, child_of(other, key), selector_parts, depth + 1, &block)
+      end
+    end
+  end
+
+  def child_of(obj, key)
     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 }
+    when Hash, Array then obj[key]
     end
   end
 
-  def max_depth(obj)
+  # The loops below run once per node of the document, so they index by hand:
+  # each_with_index and Integer#times allocate per call. Most nodes fail on
+  # their own key, which is checked before the rest of the suffix.
+  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]
+        last = parts[-1]
+        if (last == :* || last == key) && path.size >= prefix_size + parts.size && suffix_matches?(path, parts)
+          matches[index] << path.dup
+        end
+        index += 1
+      end
+      collect_suffix_matches(value, end_parts, path, prefix_size, matches)
+      path.pop
+    end
+  end
+
+  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,21 +25,35 @@ 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)
+  # Normalizes the names of examples in place, for a document that already
+  # holds symbol keys.
+  def normalize_example_names!(value)
     case value
     when Hash
-      value.to_h { |k, v| [k.to_s, stringify(v)] }
+      value.each do |k, v|
+        rename_examples!(v) if k == :examples && v.is_a?(Hash)
+        normalize_example_names!(v)
+      end
     when Array
-      value.map { |v| stringify(v) }
-    else
-      value
+      value.each { |v| normalize_example_names!(v) }
     end
+    value
+  end
+
+  private
+
+  def rename_examples!(examples)
+    renamed = {}
+    examples.each { |name, example| renamed[RSpec::OpenAPI::ExampleKey.normalize(name).to_sym] = example }
+    examples.replace(renamed)
   end
 end

data/lib/rspec/openapi/minitest_hooks.rb

@@ -53,7 +53,8 @@ if ENV['OPENAPI']
 
   Minitest.after_run do
     RSpec::OpenAPI::ParallelRecords.merge!
-    result_recorder = RSpec::OpenAPI::ResultRecorder.new(RSpec::OpenAPI.path_records)
+    partial = RSpec::OpenAPI::PartialRun.minitest?
+    result_recorder = RSpec::OpenAPI::ResultRecorder.new(RSpec::OpenAPI.path_records, partial: partial)
     result_recorder.record_results!
     puts result_recorder.error_message if result_recorder.errors?
   end