rspec-openapi 0.28.0 → 0.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43c486a798aeae6de0f9ecbec34ab2b69a11bb2b1ff053011110c611e5151fc0
-  data.tar.gz: f483a6aca96935df40e9b34386b34548f3322982935c3801bab33ee72d20746e
+  metadata.gz: 2ce922f425644ad7ab8645bf2dcd7df5f93085e5e15cae1f826feff526fc96f6
+  data.tar.gz: 19b7d372d3a1324903ec229f96292afdf738f99e492d76c16d281b9323e369f1
 SHA512:
-  metadata.gz: 7860f7a5030487e9671ee926bcf27967c827a4d80f6119eca70c8e9b330c296a5813bc8412d3b210e679700baef2d8710bcd9c9ca24c8b5890a14d90823f8c36
-  data.tar.gz: c2d9e3aaab37b25acc4d1ce563076a2fcb151f33a699268d9035d1559b428f75a75dab52394d0810a0443f031e9f3f338e9996320e5c258b598d0262a71bf1a0
+  metadata.gz: fe915320f2594675a5930eb28dd580f99fe4377e3c8dea443656d0de171187dd8cd30f2bbac720ea5c2a19271001e734740d09e472ee0cf7987caf89e11ebad6
+  data.tar.gz: 2f41de3cafeeeb044748cf71bf6cd8163f4d083d145ea8c9adbf6dfeb57336d2582c1280086c5e008a8f679e7a03f780eca4e4a76b9ef741c3d2e40633d21d48

data/README.md

@@ -116,6 +116,10 @@ RSpec::OpenAPI.path = 'doc/schema.yaml'
 # Change the output type to JSON
 RSpec::OpenAPI.path = 'doc/schema.json'
 
+# Or emit the same schema in multiple formats from a single run by passing an array.
+# The output format of each file is still chosen by its extension (`.json` -> JSON, otherwise YAML).
+RSpec::OpenAPI.path = ['doc/openapi.yaml', 'doc/openapi.json']
+
 # Or generate multiple partial schema files, given an RSpec example
 RSpec::OpenAPI.path = -> (example) {
   case example.file_path
@@ -125,6 +129,12 @@ RSpec::OpenAPI.path = -> (example) {
   end
 }
 
+# The two can be combined: a proc may also return an array to fan a partial schema out to multiple formats.
+RSpec::OpenAPI.path = -> (example) {
+  base = example.file_path.match?(%r[spec/requests/api/v2/]) ? 'doc/openapi/v2' : 'doc/openapi'
+  ["#{base}.yaml", "#{base}.json"]
+}
+
 # Change the default title of the generated schema
 RSpec::OpenAPI.title = 'OpenAPI Documentation'
 
@@ -149,6 +159,10 @@ RSpec::OpenAPI.enable_example_summary = false
 # Change `info.version`
 RSpec::OpenAPI.application_version = '1.0.0'
 
+# Change the target OpenAPI version (defaults to '3.2.0').
+# Use a 3.0.x string to keep the previous output, or a 3.1.x string.
+RSpec::OpenAPI.openapi_version = '3.0.3'
+
 # Set the info header details
 RSpec::OpenAPI.info = {
   description: 'My beautiful API',
@@ -177,6 +191,14 @@ RSpec::OpenAPI.security_schemes = {
   },
 }
 
+# Set root-level `tags` definitions, emitted verbatim.
+#
+# OpenAPI 3.2+: Structured fields such as `summary`, `parent` and `kind` are allowed.
+RSpec::OpenAPI.root_tags = [
+  { name: 'Users', summary: 'User management', kind: 'nav' },
+  { name: 'Admin', parent: 'Users' },
+]
+
 # Generate a comment on top of a schema file
 RSpec::OpenAPI.comment = <<~EOS
   This file is auto-generated by rspec-openapi https://github.com/k0kubun/rspec-openapi
@@ -190,10 +212,16 @@ RSpec::OpenAPI.description_builder = -> (example) { example.description }
 
 # Generate a custom summary, given an RSpec example
 # This example uses the summary from the example_group.
+# NOTE: a fixed `dig` only reaches one specific depth. `summary` declared on an
+# ancestor group is already inherited automatically (see "Inheritance of
+# `openapi:` metadata"), so a builder is only needed for fully custom logic.
 RSpec::OpenAPI.summary_builder = ->(example) { example.metadata.dig(:example_group, :openapi, :summary) }
 
 # Generate a custom tags, given an RSpec example
-# This example uses the tags from the parent_example_group
+# This example uses the tags from the parent_example_group.
+# NOTE: `dig(:example_group, :parent_example_group, ...)` only matches tags
+# declared exactly two levels up; it won't find tags on deeper ancestors. Rely
+# on the built-in inheritance unless you need custom resolution.
 RSpec::OpenAPI.tags_builder = -> (example) { example.metadata.dig(:example_group, :parent_example_group, :openapi, :tags) }
 
 # Configure custom format for specific properties
@@ -222,6 +250,46 @@ RSpec::OpenAPI.post_process_hook = -> (path, records, spec) do
 end
 ```
 
+### OpenAPI version
+
+The generated `openapi` version defaults to `3.2.0` (the latest). OpenAPI 3.1+ is aligned with
+JSON Schema 2020-12, so nullable values are expressed via the type array instead of the `nullable` keyword.
+
+```yaml
+# 3.0 (set RSpec::OpenAPI.openapi_version = '3.0.x')
+name:
+  type: string
+  nullable: true
+```
+
+```yaml
+# 3.1 (set RSpec::OpenAPI.openapi_version = '3.1.x')
+# 3.2 (set RSpec::OpenAPI.openapi_version = '3.2.x')
+name:
+  type:
+  - string
+  - null
+```
+
+- Set `RSpec::OpenAPI.openapi_version` to a `3.0.x` string to keep the previous `nullable: true` output.
+- A `3.1.x` string produces the same schema shapes as the default `3.2.0`; they differ only in the reported
+  version and the 3.2-only constructs described below (`query` / `additionalOperations` / `itemSchema`).
+
+Upgrade note: an existing file is read regardless of its version, so the first `OPENAPI=1` run after upgrading
+rewrites it to the new default (e.g. `3.0.3` -> `3.2.0`, `nullable: true` -> a `null` type). Pin
+`RSpec::OpenAPI.openapi_version = '3.0.3'` to opt out.
+
+### Supported OpenAPI features
+
+| Feature |  OpenAPI 3.0.x   | 3.1.x | 3.2.x (default) |
+|---|:----------------:|:---:|:---:|
+| Core generation (paths / schemas / examples) |        ✓         | ✓ | ✓ |
+| Null representation | `nullable: true` | type array `[..., 'null']` | type array `[..., 'null']` |
+| Structured root tags (`summary` / `parent` / `kind`) |    name only     | name only | ✓ |
+| `query` field (QUERY method) |        —         | — | ✓ |
+| `additionalOperations` (non-standard verbs: COPY, MOVE, …) |        —         | — | ✓ |
+| Streaming `itemSchema` (jsonl / ndjson / json-seq / SSE) |        —         | — | ✓ |
+
 ### Can I use rspec-openapi with `$ref` to minimize duplication of schema?
 
 Yes, rspec-openapi v0.7.0+ supports [`$ref` mechanism](https://swagger.io/docs/specification/using-ref/) and generates
@@ -369,6 +437,59 @@ end
 
 **NOTE**: `description` key will override also the one provided by `RSpec::OpenAPI.description_builder` method.
 
+### Inheritance of `openapi:` metadata
+
+`openapi:` metadata is inherited from the surrounding `describe`/`context` groups down to each
+example, at any nesting depth. Inner levels override outer ones key by key, so a nested group only
+needs to declare the keys it wants to change:
+
+```rb
+describe 'GET /tables', openapi: { summary: 'Get a list of tables', tags: %w[Table] } do
+  context 'with pagination', openapi: { example_mode: :multiple } do
+    # This example inherits summary: 'Get a list of tables' and tags: ['Table']
+    # from the outer describe, and adds example_mode: :multiple.
+    it { get '/tables', params: { page: 1 } }
+  end
+end
+```
+
+The merge happens at the top level of the `openapi:` hash. Scalar keys (`summary`, `operation_id`,
+…) follow last-wins, and a nested level that re-declares a structured key (`tags`, `security`,
+`enum`, …) replaces the inherited value for that key rather than deep-merging it.
+
+### Selecting which request to document (`request_pattern`)
+
+By default rspec-openapi documents the *last* request/response exchange issued in an example.
+When a single example performs several requests on the same path (for example a `DELETE`
+followed by a `GET` that asserts the resource is gone), that trailing request would otherwise
+overwrite the operation you actually want to document.
+
+Use the `request_pattern` metadata to pick the exchange explicitly. Its value is a
+`"<HTTP method> <path>"` string, where the path may use `{param}` placeholders:
+
+```rb
+describe 'Deleting a widget',
+         openapi: { summary: 'Delete a widget', request_pattern: 'DELETE /widgets/{id}' } do
+  it 'deletes the widget and verifies it is gone' do
+    delete '/widgets/1'
+    expect(response.status).to eq(200)
+
+    # Without request_pattern this trailing GET would become the documented
+    # exchange; the selector keeps the DELETE above as the operation instead.
+    get '/widgets/1?missing=1'
+    expect(response.status).to eq(404)
+  end
+end
+```
+
+- Each `{param}` placeholder matches a single path segment independently, so multi-segment
+  templates such as `'DELETE /orgs/{org_id}/members/{user_id}'` work as expected.
+- When several requests match the pattern, the last one wins.
+- It works for both Rails (`ActionDispatch::IntegrationTest`) and `Rack::Test`-based specs
+  (e.g. Roda, Hanami).
+- If the pattern can't be parsed, or no request issued in the example matches it, generation
+  fails fast with a message listing the requests that were actually recorded.
+
 ### Enum Support
 
 You can specify enum values for string properties that should have a fixed set of allowed values. Since enums cannot be

data/lib/rspec/openapi/default_schema.rb

@@ -3,7 +3,7 @@
 class << RSpec::OpenAPI::DefaultSchema = Object.new
   def build(title)
     spec = {
-      openapi: '3.0.3',
+      openapi: RSpec::OpenAPI.openapi_version,
       info: {
         title: title,
         version: RSpec::OpenAPI.application_version,
@@ -18,6 +18,8 @@ class << RSpec::OpenAPI::DefaultSchema = Object.new
       }
     end
 
+    spec[:tags] = RSpec::OpenAPI.root_tags if RSpec::OpenAPI.root_tags.present?
+
     spec.freeze
   end
 end

data/lib/rspec/openapi/exchange_recorder.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module RSpec::OpenAPI::ExchangeRecorder
+  THREAD_KEY = :rspec_openapi_exchanges
+  VERBS = [:get, :post, :put, :patch, :delete, :head, :options].freeze
+
+  module VerbTracking
+    VERBS.each do |verb|
+      define_method(verb) do |*args, &block|
+        result = super(*args, &block)
+        RSpec::OpenAPI::ExchangeRecorder.capture_from_context(self)
+        result
+      end
+      ruby2_keywords(verb)
+    end
+  end
+
+  class << self
+    def reset!(example)
+      if pattern_for(example)
+        example.example_group.prepend(VerbTracking)
+        Thread.current[THREAD_KEY] = []
+      else
+        Thread.current[THREAD_KEY] = nil
+      end
+    end
+
+    def pattern_for(example)
+      SharedExtractor.merge_openapi_metadata(example.metadata)[:request_pattern]
+    end
+
+    def capture_from_context(context)
+      exchanges = Thread.current[THREAD_KEY]
+      return unless exchanges
+
+      exchanges << build_exchange(context)
+    end
+
+    # Returns the exchange matching a `"METHOD /path/template"` pattern.
+    #
+    # @param [String] pattern e.g. "DELETE /resources/{id}"
+    # @return [Array(ActionDispatch::Request, ActionDispatch::TestResponse)]
+    def fetch(pattern)
+      method, path_template = parse_pattern(pattern)
+      path_matcher = path_template_to_regexp(path_template)
+
+      found = recorded.reverse_each.find do |request, _response|
+        request.request_method.to_s.upcase == method && request.path.match?(path_matcher)
+      end
+      return found if found
+
+      raise ArgumentError, no_match_message(pattern)
+    end
+
+    private
+
+    def recorded
+      Thread.current[THREAD_KEY]
+    end
+
+    def parse_pattern(pattern)
+      match = %r{\A(\S+)\s+(/\S*)\z}.match(pattern.to_s.strip)
+      unless match
+        raise ArgumentError,
+              "[rspec-openapi] Invalid request_pattern #{pattern.inspect}. " \
+              'Expected "<HTTP method> <path>", e.g. "DELETE /widgets/{id}".'
+      end
+
+      [match[1].upcase, match[2]]
+    end
+
+    def no_match_message(pattern)
+      issued = recorded.map { |request, _response| "#{request.request_method} #{request.path}" }
+      listing = issued.empty? ? '(no requests were recorded)' : issued.join(', ')
+      "[rspec-openapi] request_pattern #{pattern.inspect} did not match any request " \
+        "issued in this example. Recorded requests: #{listing}."
+    end
+
+    def path_template_to_regexp(template)
+      segments = template.split(/\{[^}]+\}/, -1)
+      pattern = segments.map { |segment| Regexp.escape(segment) }.join('[^/]+')
+      /\A#{pattern}\z/
+    end
+
+    def build_exchange(context)
+      if context.respond_to?(:last_request)
+        SharedExtractor.build_request_response(context.last_request.env, context.last_response.to_a)
+      else
+        session = context.instance_variable_get(:@integration_session)
+        SharedExtractor.build_request_response(session.request.env, session.response.to_a)
+      end
+    end
+  end
+end

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

@@ -71,11 +71,7 @@ class << RSpec::OpenAPI::Extractors::Hanami = Object.new
 
   # @param [RSpec::ExampleGroups::*] context
   def request_response(context)
-    request = ActionDispatch::Request.new(context.last_request.env)
-    request.body.rewind if request.body.respond_to?(:rewind)
-    response = ActionDispatch::TestResponse.new(*context.last_response.to_a)
-
-    [request, response]
+    SharedExtractor.build_request_response(context.last_request.env, context.last_response.to_a)
   end
 
   private

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

@@ -17,10 +17,6 @@ class << RSpec::OpenAPI::Extractors::Rack = Object.new
 
   # @param [RSpec::ExampleGroups::*] context
   def request_response(context)
-    request = ActionDispatch::Request.new(context.last_request.env)
-    request.body.rewind if request.body.respond_to?(:rewind)
-    response = ActionDispatch::TestResponse.new(*context.last_response.to_a)
-
-    [request, response]
+    SharedExtractor.build_request_response(context.last_request.env, context.last_response.to_a)
   end
 end

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

@@ -12,6 +12,12 @@ class SharedExtractor
     opt in early.
   MSG
 
+  def self.build_request_response(env, response_array)
+    request = ActionDispatch::Request.new(env)
+    request.body.rewind if request.body.respond_to?(:rewind)
+    [request, ActionDispatch::TestResponse.new(*response_array)]
+  end
+
   def self.attributes(example)
     metadata = merge_openapi_metadata(example.metadata)
     request_example_mode, response_example_mode = normalize_example_mode(metadata[:example_mode], example)
@@ -86,14 +92,12 @@ class SharedExtractor
 
   def self.collect_openapi_metadata(metadata)
     [].tap do |result|
-      current = metadata
-
-      while current
-        [current[:example_group], current].each do |meta|
-          result.unshift(meta[:openapi]) if meta&.dig(:openapi)
-        end
+      result.unshift(metadata[:openapi]) if metadata[:openapi]
 
-        current = current[:parent_example_group]
+      group = metadata.fetch(:example_group) { metadata[:parent_example_group] }
+      while group
+        result.unshift(group[:openapi]) if group[:openapi]
+        group = group[:parent_example_group]
       end
     end
   end

data/lib/rspec/openapi/nullable_converter.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# 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
+
+  def to_json_schema!(node)
+    each_schema(node) { |schema| nullable_to_type_null!(schema) }
+    node
+  end
+
+  def normalize!(node)
+    each_schema(node) { |schema| type_null_to_nullable!(schema) }
+    node
+  end
+
+  private
+
+  def nullable_to_type_null!(schema)
+    return unless schema.delete(:nullable)
+
+    schema[:type] =
+      case (type = schema[:type])
+      when nil then 'null'
+      else [type, 'null']
+      end
+  end
+
+  def type_null_to_nullable!(schema)
+    case (type = schema[:type])
+    when 'null'
+      schema.delete(:type)
+      schema[:nullable] = true
+    when Array
+      return unless type.include?('null')
+
+      rest = type - ['null']
+      if rest.empty?
+        schema.delete(:type)
+      else
+        schema[:type] = rest.one? ? rest.first : rest
+      end
+      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/operation_converter.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Moves non-standard HTTP methods between the internal flat form
+# (`paths.<path>.<method>`) and the 3.2 `additionalOperations` map. 3.2 keeps the
+# 8 standard methods plus `query` as fixed fields; other verbs (COPY, MOVE, ...)
+# go under `additionalOperations`. normalize! on read, to_additional_operations! on write.
+class << RSpec::OpenAPI::OperationConverter = Object.new
+  FIXED_METHODS = [:get, :put, :post, :delete, :options, :head, :patch, :trace, :query].freeze
+  # Path Item fields that are not operations.
+  PATH_ITEM_METADATA = [:summary, :description, :servers, :parameters, :additionalOperations].push(:$ref).freeze
+
+  def to_additional_operations!(spec)
+    each_path_item(spec) { |item| relocate_non_standard!(item) }
+    spec
+  end
+
+  def normalize!(spec)
+    each_path_item(spec) { |item| inline_additional_operations!(item) }
+    spec
+  end
+
+  private
+
+  def relocate_non_standard!(item)
+    non_standard = item.keys - FIXED_METHODS - PATH_ITEM_METADATA
+    non_standard.each do |method|
+      additional = (item[:additionalOperations] ||= {})
+      additional[method.to_s.upcase.to_sym] = item.delete(method)
+    end
+  end
+
+  def inline_additional_operations!(item)
+    additional = item.delete(:additionalOperations)
+    return unless additional.is_a?(Hash)
+
+    additional.each { |verb, operation| item[verb.to_s.downcase.to_sym] = operation }
+  end
+
+  def each_path_item(spec)
+    paths = spec[:paths]
+    return spec unless paths.is_a?(Hash)
+
+    paths.each_value { |item| yield item if item.is_a?(Hash) }
+    spec
+  end
+end

data/lib/rspec/openapi/record_builder.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'logger'
 require 'action_dispatch'
 require 'rspec/openapi/record'
 
@@ -8,7 +9,7 @@ class << RSpec::OpenAPI::RecordBuilder = Object.new
   # @param [RSpec::Core::Example] example
   # @return [RSpec::OpenAPI::Record,nil]
   def build(context, example:, extractor:)
-    request, response = extractor.request_response(context)
+    request, response = select_request_response(context, example, extractor)
     return if request.nil?
 
     attributes = extractor.request_attributes(request, example)
@@ -20,6 +21,13 @@ class << RSpec::OpenAPI::RecordBuilder = Object.new
 
   private
 
+  def select_request_response(context, example, extractor)
+    pattern = RSpec::OpenAPI::ExchangeRecorder.pattern_for(example)
+    return RSpec::OpenAPI::ExchangeRecorder.fetch(pattern) if pattern
+
+    extractor.request_response(context)
+  end
+
   def build_record(title, request, response, attributes)
     request_headers, response_headers = extract_headers(request, response)
     RSpec::OpenAPI::Record.new(
@@ -42,6 +50,8 @@ class << RSpec::OpenAPI::RecordBuilder = Object.new
   def safe_parse_body(response, media_type)
     # Use raw body, because Nokogiri-parsed HTML are modified (new lines injection, meta injection, and so on) :(
     return response.body if media_type == 'text/html'
+    # Keep streaming bodies raw so they can be split per item (see StreamParser).
+    return response.body if RSpec::OpenAPI.sequential_media_type?(media_type)
 
     response.parsed_body
   rescue JSON::ParserError

data/lib/rspec/openapi/result_recorder.rb

@@ -7,31 +7,16 @@ class RSpec::OpenAPI::ResultRecorder
   end
 
   def record_results!
-    @path_records.each do |path, records|
-      # Look for a path-specific config file and run it.
-      config_file = File.join(File.dirname(path), RSpec::OpenAPI.config_filename)
-      begin
-        require config_file if File.exist?(config_file)
-      rescue StandardError => e
-        puts "WARNING: Unable to load #{config_file}: #{e}"
-      end
+    @path_records.each do |paths, records|
+      # A single record set may target multiple output files (e.g. both YAML and
+      # JSON). The first path is the canonical source we read/merge into; the rest
+      # mirror the same built spec, each formatted by its own extension.
+      primary, *mirrors = Array(paths)
+      next if primary.nil?
 
-      title = records.first.title
-      RSpec::OpenAPI::SchemaFile.new(path).edit do |spec|
-        schema = RSpec::OpenAPI::DefaultSchema.build(title)
-        schema[:info].merge!(RSpec::OpenAPI.info)
-        RSpec::OpenAPI::SchemaMerger.merge!(spec, schema)
-        new_from_zero = {}
-        records.each do |record|
-          record_schema = RSpec::OpenAPI::SchemaBuilder.build(record)
-          RSpec::OpenAPI::SchemaMerger.merge!(spec, record_schema)
-          RSpec::OpenAPI::SchemaMerger.merge!(new_from_zero, record_schema)
-        rescue StandardError, NotImplementedError => e # e.g. SchemaBuilder raises a NotImplementedError
-          @error_records[e] = record # Avoid failing the build
-        end
-        cleanup_schema!(new_from_zero, spec)
-        execute_post_process_hook(path, records, spec)
-      end
+      load_path_config(primary)
+      built_spec = build_spec(primary, records)
+      mirrors.each { |mirror_path| RSpec::OpenAPI::SchemaFile.new(mirror_path).write(built_spec) }
     end
   end
 
@@ -49,6 +34,37 @@ class RSpec::OpenAPI::ResultRecorder
 
   private
 
+  # Look for a path-specific config file and run it.
+  def load_path_config(path)
+    config_file = File.join(File.dirname(path), RSpec::OpenAPI.config_filename)
+    require config_file if File.exist?(config_file)
+  rescue StandardError => e
+    puts "WARNING: Unable to load #{config_file}: #{e}"
+  end
+
+  def build_spec(primary, records)
+    title = records.first.title
+    RSpec::OpenAPI::SchemaFile.new(primary).edit do |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)
+      RSpec::OpenAPI::SchemaMerger.merge!(spec, schema)
+      new_from_zero = {}
+      records.each do |record|
+        record_schema = RSpec::OpenAPI::SchemaBuilder.build(record)
+        RSpec::OpenAPI::SchemaMerger.merge!(spec, record_schema)
+        RSpec::OpenAPI::SchemaMerger.merge!(new_from_zero, record_schema)
+      rescue StandardError, NotImplementedError => e # e.g. SchemaBuilder raises a NotImplementedError
+        @error_records[e] = record # Avoid failing the build
+      end
+      cleanup_schema!(new_from_zero, spec)
+      execute_post_process_hook(primary, records, spec)
+    end
+  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)
   end
@@ -58,6 +74,8 @@ class RSpec::OpenAPI::ResultRecorder
     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::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?
   end
 end

data/lib/rspec/openapi/rspec_hooks.rb

@@ -2,6 +2,10 @@
 
 require 'rspec/core'
 
+RSpec.configuration.before(:each) do |example|
+  RSpec::OpenAPI::ExchangeRecorder.reset!(example)
+end
+
 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 }

data/lib/rspec/openapi/schema_builder.rb

@@ -56,6 +56,12 @@ class << RSpec::OpenAPI::SchemaBuilder
     disposition = normalize_content_disposition(record.response_content_disposition)
     content_type = normalize_content_type(record.response_content_type)
     ctx = BuildContext.new(record: record, context: :response)
+
+    if RSpec::OpenAPI.supports_item_schema? && RSpec::OpenAPI.sequential_media_type?(content_type)
+      item_schema = build_stream_item_schema(record.response_body, content_type, ctx)
+      return { content_type => { itemSchema: item_schema } } if item_schema
+    end
+
     schema = build_property(record.response_body, ctx, disposition: disposition)
     example = response_example(record, disposition: disposition)
 
@@ -63,6 +69,14 @@ class << RSpec::OpenAPI::SchemaBuilder
     { content_type => body }
   end
 
+  def build_stream_item_schema(raw, content_type, ctx)
+    items = RSpec::OpenAPI::StreamParser.items(raw, content_type)
+    return nil if items.empty?
+
+    variations = items.map { |item| build_property(item, ctx) }
+    build_merged_schema_from_variations(variations)
+  end
+
   # Returns the per-content-type body (schema + optional example/examples).
   # Shared by response content and request body to keep example_mode handling in one place.
   def build_example_body(schema, record, mode:, example:)

data/lib/rspec/openapi/schema_file.rb

@@ -14,11 +14,30 @@ class RSpec::OpenAPI::SchemaFile
     @path = path
   end
 
+  # Reads the existing spec, lets the block mutate it, writes the result back
+  # and returns the (symbolized) spec so it can be mirrored to other files.
+  # @return [Hash]
   def edit(&block)
     spec = read
     block.call(spec)
+    spec
   ensure
-    write(RSpec::OpenAPI::KeyTransformer.stringify(spec))
+    write(spec)
+  end
+
+  # Writes an already-built spec to this file, choosing the format from the
+  # file extension.
+  # @param [Hash] spec
+  def write(spec)
+    stringified = RSpec::OpenAPI::KeyTransformer.stringify(spec)
+    FileUtils.mkdir_p(File.dirname(@path))
+    output =
+      if json?
+        JSON.pretty_generate(stringified)
+      else
+        prepend_comment(YAML.dump(stringified))
+      end
+    File.write(@path, output)
   end
 
   private
@@ -33,18 +52,6 @@ class RSpec::OpenAPI::SchemaFile
     RSpec::OpenAPI::KeyTransformer.symbolize(content)
   end
 
-  # @param [Hash] spec
-  def write(spec)
-    FileUtils.mkdir_p(File.dirname(@path))
-    output =
-      if json?
-        JSON.pretty_generate(spec)
-      else
-        prepend_comment(YAML.dump(spec))
-      end
-    File.write(@path, output)
-  end
-
   def prepend_comment(content)
     return content if RSpec::OpenAPI.comment.nil?
 

data/lib/rspec/openapi/schema_sorter.rb

@@ -4,18 +4,27 @@ class << RSpec::OpenAPI::SchemaSorter = Object.new
   # Sort some unpredictably ordered properties in a lexicographical manner to make the order more predictable.
   #
   # @param [Hash|Array]
+  # Operation containers: fixed methods sit directly under the path item, while
+  # 3.2 puts non-standard verbs (COPY, MOVE, ...) one level deeper, under
+  # `additionalOperations`. Both need the same response/content sorting, or their
+  # order follows RSpec's random execution order and produces churny diffs.
+  OPERATION_SELECTORS = ['paths.*.*', 'paths.*.additionalOperations.*'].freeze
+
   def deep_sort!(spec)
     # paths
     deep_sort_by_selector!(spec, 'paths')
 
-    # methods
+    # methods (and the additionalOperations verb map)
     deep_sort_by_selector!(spec, 'paths.*')
+    deep_sort_by_selector!(spec, 'paths.*.additionalOperations')
 
-    # response status code
-    deep_sort_by_selector!(spec, 'paths.*.*.responses')
+    OPERATION_SELECTORS.each do |operation|
+      # response status code
+      deep_sort_by_selector!(spec, "#{operation}.responses")
 
-    # content-type
-    deep_sort_by_selector!(spec, 'paths.*.*.responses.*.content')
+      # content-type
+      deep_sort_by_selector!(spec, "#{operation}.responses.*.content")
+    end
   end
 
   private

data/lib/rspec/openapi/stream_parser.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'json'
+
+# Splits a streaming body into its items (for `itemSchema`), skipping unparseable
+# chunks. Supported content types: RSpec::OpenAPI::SEQUENTIAL_MEDIA_TYPES.
+class << RSpec::OpenAPI::StreamParser = Object.new
+  def items(raw, content_type)
+    chunks =
+      case content_type
+      when 'application/json-seq' then raw.split("\x1e") # RFC 7464 record separator
+      when 'text/event-stream' then sse_data(raw)
+      else raw.split("\n") # NDJSON / JSON Lines
+      end
+
+    chunks.filter_map { |chunk| parse_json(chunk) }
+  end
+
+  private
+
+  def parse_json(chunk)
+    text = chunk.to_s.strip
+    return nil if text.empty?
+
+    JSON.parse(text)
+  rescue JSON::ParserError
+    nil
+  end
+
+  # SSE: events are blank-line separated; join the `data:` lines of each.
+  def sse_data(raw)
+    events = []
+    current = []
+    raw.each_line do |line|
+      line = line.chomp
+      if line.empty?
+        events << current.join("\n") unless current.empty?
+        current = []
+      elsif line.start_with?('data:')
+        current << line.sub(/\Adata: ?/, '')
+      end
+    end
+    events << current.join("\n") unless current.empty?
+    events
+  end
+end

data/lib/rspec/openapi/version.rb

@@ -2,6 +2,6 @@
 
 module RSpec
   module OpenAPI
-    VERSION = '0.28.0'
+    VERSION = '0.30.0'
   end
 end

data/lib/rspec/openapi.rb

@@ -3,7 +3,11 @@
 require 'rspec/openapi/version'
 require 'rspec/openapi/components_updater'
 require 'rspec/openapi/default_schema'
+require 'rspec/openapi/nullable_converter'
+require 'rspec/openapi/operation_converter'
+require 'rspec/openapi/stream_parser'
 require 'rspec/openapi/record_builder'
+require 'rspec/openapi/exchange_recorder'
 require 'rspec/openapi/result_recorder'
 require 'rspec/openapi/schema_builder'
 require 'rspec/openapi/schema_file'
@@ -18,6 +22,15 @@ require 'rspec/openapi/extractors/shared_extractor'
 require 'rspec/openapi/extractors/rack'
 
 module RSpec::OpenAPI
+  # Streaming media types whose body is a sequence of items, not one document.
+  # Their raw body is kept unparsed and split per item (see StreamParser).
+  SEQUENTIAL_MEDIA_TYPES = [
+    'application/jsonl',
+    'application/x-ndjson',
+    'application/json-seq',
+    'text/event-stream',
+  ].freeze
+
   class Config
     class << self
       attr_accessor :debug_enabled
@@ -40,9 +53,11 @@ module RSpec::OpenAPI
   @formats_builder = ->(example) { example.metadata[:formats] }
   @info = {}
   @application_version = '1.0.0'
+  @openapi_version = '3.2.0'
   @request_headers = []
   @servers = []
   @security_schemes = []
+  @root_tags = []
   @example_types = [:request]
   @response_headers = []
   @path_records = Hash.new { |h, k| h[k] = [] }
@@ -69,6 +84,7 @@ module RSpec::OpenAPI
                   :request_headers,
                   :servers,
                   :security_schemes,
+                  :root_tags,
                   :example_types,
                   :response_headers,
                   :path_records,
@@ -76,7 +92,57 @@ module RSpec::OpenAPI
                   :ignored_path_params,
                   :post_process_hook
 
-    attr_reader   :config_filename
+    attr_reader   :config_filename, :openapi_version
+
+    SUPPORTED_OPENAPI_MAJOR_MINORS = ['3.0', '3.1', '3.2'].freeze
+
+    def openapi_version=(version)
+      major_minor = Gem::Version.new(version).segments.first(2).join('.')
+      unless SUPPORTED_OPENAPI_MAJOR_MINORS.include?(major_minor)
+        raise ArgumentError, "Unsupported OpenAPI version: #{version.inspect}. " \
+                             "Supported: #{SUPPORTED_OPENAPI_MAJOR_MINORS.map { |v| "#{v}.x" }.join(', ')}"
+      end
+      @openapi_version = version
+    end
+
+    def openapi_version_at_least?(version)
+      Gem::Version.new(openapi_version) >= Gem::Version.new(version)
+    end
+
+    # 3.1+ drops `nullable` in favour of JSON Schema null types.
+    def json_schema_based?
+      openapi_version_at_least?('3.1')
+    end
+
+    # 3.2 adds the `query` field and the `additionalOperations` map.
+    def supports_additional_operations?
+      openapi_version_at_least?('3.2')
+    end
+
+    # 3.2 adds `itemSchema` for sequential (streaming) media types.
+    def supports_item_schema?
+      openapi_version_at_least?('3.2')
+    end
+
+    def sequential_media_type?(media_type)
+      SEQUENTIAL_MEDIA_TYPES.include?(media_type)
+    end
+
+    # Allow Rails request specs to issue extra verbs (e.g. QUERY); ActionDispatch
+    # otherwise rejects unknown verbs. No-op outside Rails.
+    def register_http_methods(methods)
+      # simplecov:disable branch non-Rails guard for roda/hanami; the suite always loads Rails
+      return unless defined?(ActionDispatch::Request::HTTP_METHODS)
+
+      # simplecov:enable
+      Array(methods).each do |method|
+        verb = method.to_s.upcase
+        next if ActionDispatch::Request::HTTP_METHODS.include?(verb)
+
+        ActionDispatch::Request::HTTP_METHODS << verb
+        ActionDispatch::Request::HTTP_METHOD_LOOKUP[verb] = verb.downcase.to_sym
+      end
+    end
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-openapi
 version: !ruby/object:Gem::Version
-  version: 0.28.0
+  version: 0.30.0
 platform: ruby
 authors:
 - Takashi Kokubun
@@ -66,6 +66,7 @@ files:
 - lib/rspec/openapi/components_updater.rb
 - lib/rspec/openapi/default_schema.rb
 - lib/rspec/openapi/example_key.rb
+- lib/rspec/openapi/exchange_recorder.rb
 - lib/rspec/openapi/extractors.rb
 - lib/rspec/openapi/extractors/hanami.rb
 - lib/rspec/openapi/extractors/rack.rb
@@ -74,6 +75,8 @@ files:
 - lib/rspec/openapi/hash_helper.rb
 - lib/rspec/openapi/key_transformer.rb
 - lib/rspec/openapi/minitest_hooks.rb
+- lib/rspec/openapi/nullable_converter.rb
+- lib/rspec/openapi/operation_converter.rb
 - lib/rspec/openapi/record.rb
 - lib/rspec/openapi/record_builder.rb
 - lib/rspec/openapi/result_recorder.rb
@@ -85,6 +88,7 @@ files:
 - lib/rspec/openapi/schema_merger.rb
 - lib/rspec/openapi/schema_sorter.rb
 - lib/rspec/openapi/shared_hooks.rb
+- lib/rspec/openapi/stream_parser.rb
 - lib/rspec/openapi/version.rb
 - rspec-openapi.gemspec
 homepage: https://github.com/exoego/rspec-openapi
@@ -93,7 +97,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.28.0
+  changelog_uri: https://github.com/exoego/rspec-openapi/releases/tag/v0.30.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: