rspec-openapi 0.34.0 → 0.36.0

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,6 +24,7 @@ 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])
@@ -32,7 +34,23 @@ class << RSpec::OpenAPI::NullableConverter = Object.new
       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)
@@ -49,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/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,19 +47,24 @@ 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)
       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)
-      new_from_zero = {}
+      # SchemaFile#read already symbolized the document, so no merge here needs
+      # to normalize it again.
+      RSpec::OpenAPI::SchemaMerger.merge_normalized!(spec, schema)
       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
@@ -67,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?

data/lib/rspec/openapi/rspec_hooks.rb

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

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

@@ -4,16 +4,30 @@ 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. The path is only ever looked
+  # up in the enum and additionalProperties maps of the record, so it is built
+  # for a side of a record that holds one.
+  BuildContext = Struct.new(:record, :context, :path, :key, :lookups) do
+    def self.root(record, context, path = nil, key = nil)
+      lookups = record[ENUM_MEMBERS.fetch(context)] ||
+                OVERRIDE_MEMBERS.any? { |_kind, members| record[members.fetch(context)] }
+      new(record, context, path, key, lookups)
+    end
+
     def descend(child_key)
-      self.class.new(
-        record: record, context: context, key: child_key,
-        path: path ? "#{path}.#{child_key}" : child_key.to_s,
-      )
+      self.class.new(record, context, child_path(child_key), child_key, lookups)
+    end
+
+    def child_path(child_key)
+      return nil unless lookups
+
+      path ? "#{path}.#{child_key}" : child_key.to_s
     end
 
     def for_array_items
-      self.class.new(record: record, context: context, path: path, key: nil)
+      self.class.new(record, context, path, nil, lookups)
     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
 
@@ -27,11 +27,10 @@ class << RSpec::OpenAPI::SchemaBuilder
     end
 
     def merge_non_object_item_variations(schemas)
-      nullable_only = ->(schema) { schema.keys == [:nullable] }
-      typed = schemas.reject(&nullable_only)
+      typed = schemas.reject { |schema| nullable_only?(schema) }
 
       merged = typed.size == 1 ? typed.first.dup : merge_multi(typed)
-      merged[:nullable] = true if schemas.any?(&nullable_only) && merged.is_a?(Hash)
+      merged[:nullable] = true if schemas.any? { |schema| nullable_only?(schema) } && merged.is_a?(Hash)
       merged
     end
 
@@ -43,25 +42,42 @@ class << RSpec::OpenAPI::SchemaBuilder
     def merge_property_variations(variations, allow_recursive_merge:)
       property_keys(variations).each_with_object({}) do |key, merged_props|
         all = variations.map { |v| v[:properties]&.[](key) }
-        prop_variations = all.reject { |p| p.nil? || p.keys == [:nullable] }
+        read_only = lift_read_only!(all)
+        prop_variations = all.reject { |p| p.nil? || nullable_only?(p) }
         has_nullable = nullable_present?(all, recursive: allow_recursive_merge)
 
         next if prop_variations.empty? && !has_nullable
 
-        merged_props[key] = merge_single_property(prop_variations, has_nullable,
-                                                  variations_total: variations.size,
-                                                  allow_recursive_merge: allow_recursive_merge,)
+        merged = merge_single_property(prop_variations, has_nullable,
+                                       variations_total: variations.size,
+                                       allow_recursive_merge: allow_recursive_merge,)
+        merged[:readOnly] = read_only unless read_only.nil?
+        merged_props[key] = merged
       end
     end
 
     private
 
+    # The variations of one property come from one side of one exchange, so
+    # they agree on readOnly. The merge rebuilds the schema, so the caller puts
+    # it back on the result, beside a oneOf like nullable. The schemas are the
+    # builder's own, so the flag comes off them in place.
+    def lift_read_only!(all)
+      read_only = all.find { |p| p.is_a?(Hash) && p.key?(:readOnly) }&.[](:readOnly)
+      all.each { |p| p&.delete(:readOnly) } unless read_only.nil?
+      read_only
+    end
+
     def merge_object_variations(variations)
-      {
-        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.
@@ -70,7 +86,10 @@ class << RSpec::OpenAPI::SchemaBuilder
     end
 
     def property_keys(variations)
-      variations.flat_map { |v| v[:properties]&.keys || [] }.uniq
+      keys = []
+      variations.each { |v| v[:properties]&.each_key { |key| keys << key } }
+      keys.uniq!
+      keys
     end
 
     # `recursive` mirrors merge_variations' original rule that also treats
@@ -78,10 +97,14 @@ class << RSpec::OpenAPI::SchemaBuilder
     # looks at outright nil or `{ nullable: true }` markers.
     def nullable_present?(all_props, recursive:)
       all_props.any? do |p|
-        p.nil? || (p.is_a?(Hash) && (p.keys == [:nullable] || (recursive && p[:nullable] == true)))
+        p.nil? || (p.is_a?(Hash) && (nullable_only?(p) || (recursive && p[:nullable] == true)))
       end
     end
 
+    def nullable_only?(schema)
+      schema.size == 1 && schema.key?(:nullable)
+    end
+
     def merge_single_property(prop_variations, has_nullable, variations_total:, allow_recursive_merge:)
       return { nullable: true } if prop_variations.empty?
 
@@ -112,6 +135,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 +146,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 +170,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