rspec-openapi 0.35.0 → 0.36.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7298e79ff60a23925281c724390eed37544bef37a47f7ba85e6f5ef2d28bf3f
-  data.tar.gz: b1798ffc05aa81f206b4f50e5fffeb6317ac902e113c1c3449bf1f0ed4be437d
+  metadata.gz: a9ca3c8b1eadd4f1b45f1a3c6fcfe533ac85e2eb836ff2dd849fec8f22f7a42d
+  data.tar.gz: 43ef531b0a5141c1d95e075fda5a5020b0c1792c73f4df686ce152801e7c29e7
 SHA512:
-  metadata.gz: 8d5b3eb347258591c559c26f4450179c7a329a67bc1a6b01e7f92b1666dd8ab251c604f93ac28c92387277649d5b17b94d37a38be31875f86872028e431e6fad
-  data.tar.gz: 4ee74f1f40a64081044245d88dfe01ac43a40ef397467477e99cf54ea3368b2af080c44712f3873727989cf94e7c27229e2aaed900db0df58f1cfc2d0b818005
+  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
@@ -87,6 +89,10 @@ class << RSpec::OpenAPI::ComponentsUpdater = Object.new
       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?
 
       merge_schema!(fresh_schemas, schema_name, schema_body)
     end
@@ -98,14 +104,15 @@ class << RSpec::OpenAPI::ComponentsUpdater = Object.new
     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)

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

@@ -12,6 +12,15 @@ class << RSpec::OpenAPI::HashHelper = Object.new
     matches
   end
 
+  # 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
+
   # 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
@@ -59,10 +68,15 @@ class << RSpec::OpenAPI::HashHelper = Object.new
     (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 split_selector(selector)
-    selector.split('.').map(&:to_sym)
+    SELECTOR_PARTS[selector]
   end
 
   # `path` is the stack of keys from the root to obj, pushed and popped in
@@ -84,15 +98,40 @@ class << RSpec::OpenAPI::HashHelper = Object.new
     end
   end
 
+  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, Array then obj[key]
+    end
+  end
+
   # The loops below run once per node of the document, so they index by hand:
-  # each_with_index and Integer#times allocate per call.
+  # 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]
-        matches[index] << path.dup if path.size >= prefix_size + parts.size && suffix_matches?(path, parts)
+        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)

data/lib/rspec/openapi/key_transformer.rb

@@ -34,16 +34,26 @@ class << RSpec::OpenAPI::KeyTransformer = Object.new
     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
-      result = {}
-      value.each { |k, v| result[k.to_s] = stringify(v) }
-      result
+      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

data/lib/rspec/openapi/parallel_records.rb

@@ -30,6 +30,16 @@ module RSpec::OpenAPI::ParallelRecords
   # its content, so the file itself does not need to survive the trip.
   UPLOADED_FILE_MARKER = '__rspec_openapi_uploaded_file'
 
+  # Members that hold a builder's lookup, a Proc when a builder is set.
+  LOOKUP_MEMBERS = [:formats, :response_read_only, :request_read_only].freeze
+
+  # Tags an error a lookup raised in a worker. It travels in place of the
+  # answers as [LOOKUP_ERROR_MARKER, message], a shape no answer Hash can take.
+  LOOKUP_ERROR_MARKER = '__rspec_openapi_lookup_error'
+
+  # Raised in the main process for an error a lookup raised in a worker.
+  class LookupError < StandardError; end
+
   class << self
     def worker?
       Process.pid != MAIN_PID
@@ -52,7 +62,7 @@ module RSpec::OpenAPI::ParallelRecords
 
       FileUtils.mkdir_p(dump_dir, mode: 0o700)
       encoded = RSpec::OpenAPI.path_records.transform_values do |records|
-        records.map { |record| transform_record(record) { |value| encode(value) } }
+        records.map { |record| encode_record(answer_lookups(record)) }
       end
       File.write(File.join(dump_dir, "#{Process.pid}.yaml"), YAML.dump(encoded))
     end
@@ -61,7 +71,7 @@ module RSpec::OpenAPI::ParallelRecords
       Dir.glob(File.join(dump_dir, '*.yaml')).sort.each do |file|
         records_by_path = YAML.safe_load(File.read(file), permitted_classes: permitted_classes, aliases: true)
         records_by_path.each do |path, records|
-          decoded = records.map { |record| transform_record(record) { |value| decode(value) } }
+          decoded = records.map { |record| decode_record(record) }
           RSpec::OpenAPI.path_records[path].concat(decoded)
         end
       end
@@ -83,8 +93,53 @@ module RSpec::OpenAPI::ParallelRecords
       classes
     end
 
-    def transform_record(record, &block)
-      RSpec::OpenAPI::Record.new(**record.to_h.transform_values(&block))
+    def encode_record(record)
+      RSpec::OpenAPI::Record.new(**record.to_h.transform_values { |value| encode(value) })
+    end
+
+    # Only a lookup member can hold a lookup error, so only there is one looked for.
+    def decode_record(record)
+      members = record.to_h.to_h do |member, value|
+        [member, LOOKUP_MEMBERS.include?(member) ? decode_lookup(value) : decode(value)]
+      end
+      RSpec::OpenAPI::Record.new(**members)
+    end
+
+    def decode_lookup(value)
+      return value unless value.is_a?(Array) && value.first == LOOKUP_ERROR_MARKER
+
+      message = value.last
+      ->(*) { raise LookupError, message }
+    end
+
+    # No serializer can carry a Proc. Building the schema here asks each lookup
+    # about every key the main process will ask about, and the answers travel
+    # as a Hash, which the builder reads the same way.
+    def answer_lookups(record)
+      lookups = LOOKUP_MEMBERS.select { |member| record[member].is_a?(Proc) }
+      return record if lookups.empty?
+
+      answers = lookups.to_h { |member| [member, {}] }
+      probe = record.dup
+      lookups.each { |member| probe[member] = recording_lookup(member, record[member], answers) }
+      begin
+        RSpec::OpenAPI::SchemaBuilder.build(probe)
+      rescue StandardError, NotImplementedError
+        # A value the builder cannot type, or a lookup error kept below. The
+        # main process builds this record again and reports the error itself.
+      end
+      record.dup.tap { |answered| answers.each { |member, value| answered[member] = value } }
+    end
+
+    # The main process cannot call the lookup again, so an error it raises
+    # travels in place of its answers, and decode_lookup raises it there.
+    def recording_lookup(member, lookup, answers)
+      lambda do |key|
+        answers[member][key] = lookup.call(key)
+      rescue StandardError, NotImplementedError => e
+        answers[member] = [LOOKUP_ERROR_MARKER, "#{member} lookup raised #{e.class}: #{e.message}"]
+        raise
+      end
     end
 
     # Uploads hold an open Tempfile, which no serializer can represent, so

data/lib/rspec/openapi/partial_run.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'set'
+
+# Decides whether a run adds and updates the document without removing anything.
+#
+# A run over part of the suite cannot tell an endpoint that was removed from
+# one whose spec did not run, so it removes nothing. Only a run over the whole
+# suite does. RSpec::OpenAPI.partial_update forces either mode.
+module RSpec::OpenAPI::PartialRun
+  class << self
+    # The spec file of an example that recorded a request. The run is partial
+    # when a spec file next to one of these was left out.
+    def record_file(path)
+      recorded_files << path
+    end
+
+    def rspec?
+      configured = RSpec::OpenAPI.partial_update
+      return configured unless configured.nil?
+
+      parallel_worker? || filtered? || files_left_out?
+    end
+
+    # Minitest tells nothing about the run, so only the option and the
+    # parallel_tests marker count.
+    def minitest?
+      configured = RSpec::OpenAPI.partial_update
+      configured == true || (configured.nil? && parallel_worker?)
+    end
+
+    # Printed when the run decided on its own, since the user may expect the
+    # removals of a full run.
+    def notice(partial)
+      return unless partial && RSpec::OpenAPI.partial_update.nil? && recorded_files.any?
+
+      'rspec-openapi: this run covered part of the suite, so nothing was removed from the document. ' \
+        'Run all specs to remove what no longer exists.'
+    end
+
+    private
+
+    def recorded_files
+      @recorded_files ||= Set.new
+    end
+
+    # parallel_tests marks each worker with TEST_ENV_NUMBER, an empty string
+    # for the first one. A worker sees part of the files, whichever files it
+    # got, so the directory check below cannot tell it from a full run.
+    def parallel_worker?
+      ENV.key?('TEST_ENV_NUMBER')
+    end
+
+    # -e, --tag, a line number, --only-failures, and a `fit` once an example
+    # carries it. An exclusion such as `--tag ~slow` does not narrow the run.
+    def filtered?
+      RSpec.configuration.inclusion_filter.rules.any?
+    end
+
+    # `rspec spec/requests/users_spec.rb` leaves out the other files of
+    # spec/requests. `rspec spec/requests` and `rspec spec/requests/*_spec.rb`
+    # do not, nor does a run that leaves out files of a directory that
+    # recorded nothing.
+    def files_left_out?
+      running = RSpec.configuration.files_to_run
+      recorded_files.map { |file| File.dirname(file) }.uniq.any? do |dir|
+        (spec_files_in(dir) - running).any?
+      end
+    end
+
+    # The spec files directly in dir, by the pattern and exclude pattern of
+    # the run.
+    def spec_files_in(dir)
+      config = RSpec.configuration
+      files = Dir[glob(dir, config.pattern)] - Dir[glob(dir, config.exclude_pattern)]
+      files.map { |file| File.expand_path(file) }.select { |file| File.dirname(file) == dir }
+    end
+
+    # A pattern may list alternatives, which glob as a brace group like RSpec does.
+    def glob(dir, pattern)
+      File.join(dir, "{#{pattern.to_s.gsub(/\s*,\s*/, ',')}}")
+    end
+  end
+end

data/lib/rspec/openapi/record.rb

@@ -13,6 +13,8 @@ RSpec::OpenAPI::Record = Struct.new(
   :summary,               # @param [String]  - "v1/statuses #show"
   :tags,                  # @param [Array]   - ["Status"]
   :formats,               # @param [Proc]    - ->(key) { key.end_with?('_at') ? 'date-time' : nil }
+  :response_read_only,    # @param [Proc]    - ->(key) { key == 'id' }, what a response marks readOnly
+  :request_read_only,     # @param [Proc]    - ->(key) { key == 'id' }, what a request may cancel
   :operation_id,          # @param [String]   - "request-1234"
   :description,           # @param [String]  - "returns a status"
   :example_key,           # @param [String]  - "with_flat_query_parameters"

data/lib/rspec/openapi/result_recorder.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
 class RSpec::OpenAPI::ResultRecorder
-  def initialize(path_records)
+  # @param [Boolean] partial add and update without removing anything
+  def initialize(path_records, partial: false)
     @path_records = path_records
+    @partial = partial
     @error_records = {}
   end
 
@@ -45,6 +47,10 @@ class RSpec::OpenAPI::ResultRecorder
   def build_spec(primary, records)
     title = records.first.title
     RSpec::OpenAPI::SchemaFile.new(primary).edit do |spec|
+      # The cleanup compares the document with one built from this run alone.
+      # Without an existing document nothing can be stale, so the document is
+      # that one and the records are merged once.
+      new_from_zero = spec.empty? ? spec : {}
       # Normalize an existing file back to the internal form so merge/cleanup is
       # version-agnostic; cleanup_schema! re-applies the target form.
       RSpec::OpenAPI::NullableConverter.normalize!(spec)
@@ -54,11 +60,11 @@ class RSpec::OpenAPI::ResultRecorder
       # 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)
-        RSpec::OpenAPI::SchemaMerger.merge_normalized!(spec, record_schema)
-        RSpec::OpenAPI::SchemaMerger.merge_normalized!(new_from_zero, record_schema)
+        # The document takes the schema over, so the fresh one gets a copy.
+        RSpec::OpenAPI::SchemaMerger.merge_normalized!(new_from_zero, record_schema) unless new_from_zero.equal?(spec)
+        RSpec::OpenAPI::SchemaMerger.merge_built!(spec, record_schema)
       rescue StandardError, NotImplementedError => e # e.g. SchemaBuilder raises a NotImplementedError
         @error_records[e] = record # Avoid failing the build
       end
@@ -68,14 +74,21 @@ class RSpec::OpenAPI::ResultRecorder
   end
 
   def execute_post_process_hook(path, records, spec)
-    RSpec::OpenAPI.post_process_hook.call(path, records, spec) if RSpec::OpenAPI.post_process_hook.is_a?(Proc)
+    return unless RSpec::OpenAPI.post_process_hook.is_a?(Proc)
+
+    RSpec::OpenAPI.post_process_hook.call(path, records, spec)
+    # The hook may add string keys beside the symbol ones, and the files are
+    # written from the keys as they are. Folding them keeps one entry per name.
+    spec.replace(RSpec::OpenAPI::KeyTransformer.symbolize(spec))
   end
 
   def cleanup_schema!(new_from_zero, spec)
     RSpec::OpenAPI::SchemaCleaner.cleanup_conflicting_security_parameters!(spec)
-    RSpec::OpenAPI::SchemaCleaner.cleanup!(spec, new_from_zero)
-    RSpec::OpenAPI::ComponentsUpdater.update!(spec, new_from_zero)
-    RSpec::OpenAPI::SchemaCleaner.cleanup_empty_required_array!(spec)
+    RSpec::OpenAPI::SchemaCleaner.cleanup!(spec, new_from_zero) unless @partial
+    RSpec::OpenAPI::ComponentsUpdater.update!(spec, new_from_zero, partial: @partial)
+    # After the update, which reads the request side's readOnly: false from
+    # new_from_zero, the very spec when there was no document yet.
+    RSpec::OpenAPI::SchemaCleaner.cleanup_schemas!(spec)
     RSpec::OpenAPI::OperationConverter.to_additional_operations!(spec) if RSpec::OpenAPI.supports_additional_operations?
     RSpec::OpenAPI::SchemaSorter.deep_sort!(spec)
     RSpec::OpenAPI::NullableConverter.to_json_schema!(spec) if RSpec::OpenAPI.json_schema_based?