rspec-openapi 0.25.1 → 0.27.0

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

@@ -48,44 +48,25 @@ end)
 class << RSpec::OpenAPI::Extractors::Hanami = Object.new
   # @param [ActionDispatch::Request] request
   # @param [RSpec::Core::Example] example
-  # @return Array
+  # @return [Hash]
   def request_attributes(request, example)
     route = Hanami.app.router.recognize(Rack::MockRequest.env_for(request.path, method: request.method))
 
     return RSpec::OpenAPI::Extractors::Rack.request_attributes(request, example) unless route.routable?
 
-    summary, tags, formats, operation_id, required_request_params, security, description, deprecated, example_mode,
-      example_key, example_name, response_enum, request_enum = SharedExtractor.attributes(example)
-
+    attrs = SharedExtractor.attributes(example)
     path = request.path
+    result = InspectorAnalyzer.call(request.method, replace_path_params(path, route, '/:%<key>s'))
 
     raw_path_params = route.params
-
-    result = InspectorAnalyzer.call(request.method, replace_path_params(path, route, '/:%{key}'))
-
-    summary ||= result[:summary]
-    tags ||= result[:tags]
-    path = replace_path_params(path, route, '/{%{key}}')
-
     raw_path_params = raw_path_params.slice(*(raw_path_params.keys - RSpec::OpenAPI.ignored_path_params))
 
-    [
-      path,
-      summary,
-      tags,
-      operation_id,
-      required_request_params,
-      raw_path_params,
-      description,
-      security,
-      deprecated,
-      formats,
-      example_mode,
-      example_key,
-      example_name,
-      response_enum,
-      request_enum,
-    ]
+    attrs.merge(
+      path: replace_path_params(path, route, '/{%<key>s}'),
+      path_params: raw_path_params,
+      summary: attrs[:summary] || result[:summary],
+      tags: attrs[:tags] || result[:tags],
+    )
   end
 
   # @param [RSpec::ExampleGroups::*] context
@@ -103,7 +84,7 @@ class << RSpec::OpenAPI::Extractors::Hanami = Object.new
     return path if route.params.empty?
 
     route.params.each_pair do |key, value|
-      path = path.sub("/#{value}", format % { key: key })
+      path = path.sub("/#{value}", format(format, key: key))
     end
 
     path

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

@@ -4,32 +4,15 @@
 class << RSpec::OpenAPI::Extractors::Rack = Object.new
   # @param [ActionDispatch::Request] request
   # @param [RSpec::Core::Example] example
-  # @return Array
+  # @return [Hash]
   def request_attributes(request, example)
-    summary, tags, formats, operation_id, required_request_params, security, description, deprecated, example_mode,
-      example_key, example_name, response_enum, request_enum = SharedExtractor.attributes(example)
-
-    raw_path_params = request.path_parameters
     path = request.path
-    summary ||= "#{request.method} #{path}"
-
-    [
-      path,
-      summary,
-      tags,
-      operation_id,
-      required_request_params,
-      raw_path_params,
-      description,
-      security,
-      deprecated,
-      formats,
-      example_mode,
-      example_key,
-      example_name,
-      response_enum,
-      request_enum,
-    ]
+    attrs = SharedExtractor.attributes(example)
+    attrs.merge(
+      path: path,
+      path_params: request.path_parameters,
+      summary: attrs[:summary] || "#{request.method} #{path}",
+    )
   end
 
   # @param [RSpec::ExampleGroups::*] context

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

@@ -4,7 +4,7 @@
 class << RSpec::OpenAPI::Extractors::Rails = Object.new
   # @param [ActionDispatch::Request] request
   # @param [RSpec::Core::Example] example
-  # @return Array
+  # @return [Hash]
   def request_attributes(request, example)
     # Reverse the destructive modification by Rails https://github.com/rails/rails/blob/v6.0.3.4/actionpack/lib/action_dispatch/journey/router.rb#L33-L41
     fixed_request = request.dup
@@ -16,40 +16,27 @@ class << RSpec::OpenAPI::Extractors::Rails = Object.new
 
     raise "No route matched for #{fixed_request.request_method} #{fixed_request.path_info}" if route.nil?
 
-    summary, tags, formats, operation_id, required_request_params, security, description, deprecated, example_mode,
-      example_key, example_name, response_enum, request_enum = SharedExtractor.attributes(example)
-
-    raw_path_params = request.path_parameters
-
-    summary ||= route.requirements[:action]
-    tags ||= [route.requirements[:controller]&.classify].compact
+    attrs = SharedExtractor.attributes(example)
     # :controller and :action always exist. :format is added when routes is configured as such.
     # TODO: Use .except(:controller, :action, :format) when we drop support for Ruby 2.x
+    raw_path_params = request.path_parameters
     raw_path_params = raw_path_params.slice(*(raw_path_params.keys - RSpec::OpenAPI.ignored_path_params))
 
-    summary ||= "#{request.method} #{path}"
-
-    [
-      path,
-      summary,
-      tags,
-      operation_id,
-      required_request_params,
-      raw_path_params,
-      description,
-      security,
-      deprecated,
-      formats,
-      example_mode,
-      example_key,
-      example_name,
-      response_enum,
-      request_enum,
-    ]
+    attrs.merge(
+      path: path,
+      path_params: raw_path_params,
+      summary: attrs[:summary] || route.requirements[:action] || "#{request.method} #{path}",
+      tags: attrs[:tags] || [route.requirements[:controller]&.classify].compact,
+    )
   end
 
   # @param [RSpec::ExampleGroups::*] context
   def request_response(context)
+    # Read @integration_session directly so user-defined let(:request)/let(:response)
+    # don't shadow the real ActionDispatch objects we need for OpenAPI extraction.
+    session = context.instance_variable_get(:@integration_session)
+    return [session.request, session.response] if session
+
     [context.request, context.response]
   end
 

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

@@ -2,31 +2,67 @@
 
 # Shared extractor for extracting OpenAPI metadata from RSpec examples
 class SharedExtractor
-  VALID_EXAMPLE_MODES = %i[none single multiple].freeze
+  VALID_EXAMPLE_MODES = [:none, :single, :multiple].freeze
+
+  EXAMPLE_MODE_MULTIPLE_SHORTHAND_WARNING = <<~MSG.tr("\n", ' ').strip.freeze
+    [rspec-openapi] DEPRECATION: example_mode: :multiple currently means
+    { request: :single, response: :multiple }. A future major version will
+    change it to { request: :multiple, response: :multiple } (both sides
+    multi). Specify the hash form explicitly to lock in current behavior or
+    opt in early.
+  MSG
 
   def self.attributes(example)
     metadata = merge_openapi_metadata(example.metadata)
-    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)
-    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]
-    example_mode = normalize_example_mode(metadata[:example_mode], example)
+    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)
+    # Enum support: response_enum and request_enum can override the general enum
+    base_enum = normalize_enum(metadata[:enum])
+
+    {
+      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),
+      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_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,
+      request_enum: normalize_enum(metadata[:request_enum]) || base_enum,
+      response_additional_properties: response_additional_properties,
+      request_additional_properties: request_additional_properties,
+      response_hybrid_additional_properties: response_hybrid_additional_properties,
+      request_hybrid_additional_properties: request_hybrid_additional_properties,
+    }
+  end
+
+  def self.resolve_example_key(metadata, example)
     example_name = metadata[:example_name] || RSpec::OpenAPI.example_name_builder.call(example)
     raw_example_key = metadata[:example_key] || example_name
     example_key = RSpec::OpenAPI::ExampleKey.normalize(raw_example_key)
     example_key = 'default' if example_key.nil? || example_key.empty?
+    example_key
+  end
 
-    # Enum support: response_enum and request_enum can override the general enum
-    base_enum = normalize_enum(metadata[:enum])
-    response_enum = normalize_enum(metadata[:response_enum]) || base_enum
-    request_enum = normalize_enum(metadata[:request_enum]) || base_enum
+  def self.resolve_additional_properties(metadata)
+    base = normalize_additional_properties(metadata[:additional_properties])
+    response = normalize_additional_properties(metadata[:response_additional_properties]) || base
+    request = normalize_additional_properties(metadata[:request_additional_properties]) || base
+    [response, request]
+  end
 
-    [summary, tags, formats, operation_id, required_request_params, security, description, deprecated, example_mode,
-     example_key, example_name, response_enum, request_enum,]
+  def self.resolve_hybrid_additional_properties(metadata)
+    base = normalize_additional_properties(metadata[:hybrid_additional_properties])
+    response = normalize_additional_properties(metadata[:response_hybrid_additional_properties]) || base
+    request = normalize_additional_properties(metadata[:request_hybrid_additional_properties]) || base
+    [response, request]
   end
 
   def self.normalize_enum(enum_hash)
@@ -36,6 +72,14 @@ class SharedExtractor
     enum_hash.transform_keys(&:to_s)
   end
 
+  def self.normalize_additional_properties(hash)
+    return nil if hash.nil? || hash.empty?
+
+    hash.each_with_object({}) do |(path, schema), result|
+      result[path.to_s] = RSpec::OpenAPI::KeyTransformer.symbolize(schema)
+    end
+  end
+
   def self.merge_openapi_metadata(metadata)
     collect_openapi_metadata(metadata).reduce({}, &:merge)
   end
@@ -54,9 +98,33 @@ class SharedExtractor
     end
   end
 
+  # Returns [request_mode, response_mode]. Accepts either a bare Symbol/String
+  # (applied to both sides, except :multiple which is treated as a backward-compat
+  # shorthand for { request: :single, response: :multiple } and emits a one-time
+  # deprecation warning) or a Hash with :request / :response keys.
   def self.normalize_example_mode(value, example = nil)
-    return :single if value.nil?
+    return [:single, :single] if value.nil?
+
+    case value
+    when Hash
+      [
+        normalize_example_mode_hash_value(value, :request, example),
+        normalize_example_mode_hash_value(value, :response, example),
+      ]
+    when Symbol, String
+      mode = coerce_example_mode_value(value, example)
+      if mode == :multiple
+        warn_example_mode_multiple_shorthand
+        [:single, :multiple]
+      else
+        [mode, mode]
+      end
+    else
+      raise ArgumentError, example_mode_error(value, example)
+    end
+  end
 
+  def self.coerce_example_mode_value(value, example)
     raise ArgumentError, example_mode_error(value, example) unless value.is_a?(String) || value.is_a?(Symbol)
 
     mode = value.to_s.strip.downcase.to_sym
@@ -65,9 +133,25 @@ class SharedExtractor
     raise ArgumentError, example_mode_error(value, example)
   end
 
+  def self.normalize_example_mode_hash_value(hash, key, example)
+    raw = hash[key]
+    raw = hash[key.to_s] if raw.nil?
+    return :single if raw.nil?
+
+    coerce_example_mode_value(raw, example)
+  end
+
+  def self.warn_example_mode_multiple_shorthand
+    return if @warned_example_mode_multiple_shorthand
+
+    @warned_example_mode_multiple_shorthand = true
+    Kernel.warn(EXAMPLE_MODE_MULTIPLE_SHORTHAND_WARNING)
+  end
+
   def self.example_mode_error(value, example)
     context = example&.full_description
     context = " (example: #{context})" if context
-    "example_mode must be one of #{VALID_EXAMPLE_MODES.inspect}, got #{value.inspect}#{context}"
+    "example_mode must be a Symbol/String in #{VALID_EXAMPLE_MODES.inspect} " \
+      "or a Hash with :request/:response keys, got #{value.inspect}#{context}"
   end
 end

data/lib/rspec/openapi/record.rb

@@ -20,7 +20,8 @@ RSpec::OpenAPI::Record = Struct.new(
   :security,              # @param [Array]  - [{securityScheme1: []}]
   :deprecated,            # @param [Boolean] - true
   :example_enabled,       # @param [Boolean] - true
-  :example_mode,          # @param [Symbol]  - :none | :single | :multiple
+  :request_example_mode,  # @param [Symbol]  - :none | :single | :multiple
+  :response_example_mode, # @param [Symbol]  - :none | :single | :multiple
   :status,                # @param [Integer] - 200
   :response_body,         # @param [Object]  - {"status" => "ok"}
   :response_headers,      # @param [Array]  - [["header_key1", "header_value1"], ["header_key2", "header_value2"]]
@@ -28,5 +29,9 @@ RSpec::OpenAPI::Record = Struct.new(
   :response_content_disposition, # @param [String]  - "inline"
   :response_enum,         # @param [Hash]    - {"status" => ["active", "inactive"], "user.role" => ["admin", "user"]}
   :request_enum,          # @param [Hash]    - {"type" => ["create", "update"]}
+  :response_additional_properties, # @param [Hash] - {"data" => { type: "boolean" }}
+  :request_additional_properties,  # @param [Hash] - {"meta" => { type: "string" }}
+  :response_hybrid_additional_properties, # @param [Hash] - {"data" => { type: "string" }}
+  :request_hybrid_additional_properties,  # @param [Hash] - {"meta" => { type: "string" }}
   keyword_init: true,
 )

data/lib/rspec/openapi/record_builder.rb

@@ -11,48 +11,34 @@ class << RSpec::OpenAPI::RecordBuilder = Object.new
     request, response = extractor.request_response(context)
     return if request.nil?
 
+    attributes = extractor.request_attributes(request, example)
+    return if RSpec::OpenAPI.ignored_paths.any? { |ignored_path| attributes[:path].match?(ignored_path) }
+
     title = RSpec::OpenAPI.title.then { |t| t.is_a?(Proc) ? t.call(example) : t }
-    path, summary, tags, operation_id, required_request_params, raw_path_params,
-      description, security, deprecated, formats, example_mode, example_key,
-      example_name, response_enum, request_enum = extractor.request_attributes(request, example)
+    build_record(title, request, response, attributes)
+  end
 
-    return if RSpec::OpenAPI.ignored_paths.any? { |ignored_path| path.match?(ignored_path) }
+  private
 
+  def build_record(title, request, response, attributes)
     request_headers, response_headers = extract_headers(request, response)
-
     RSpec::OpenAPI::Record.new(
       title: title,
       http_method: request.method,
-      path: path,
-      path_params: raw_path_params,
       query_params: request.query_parameters,
       request_params: raw_request_params(request),
-      required_request_params: required_request_params,
       request_content_type: request.media_type,
       request_headers: request_headers,
-      summary: summary,
-      tags: tags,
-      formats: formats,
-      operation_id: operation_id,
-      description: description,
-      security: security,
-      deprecated: deprecated,
       status: response.status,
       response_body: safe_parse_body(response, response.media_type),
       response_headers: response_headers,
       response_content_type: response.media_type,
       response_content_disposition: response.header['Content-Disposition'],
       example_enabled: RSpec::OpenAPI.enable_example,
-      example_mode: example_mode,
-      example_key: example_key,
-      example_name: example_name,
-      response_enum: response_enum,
-      request_enum: request_enum,
+      **attributes,
     ).freeze
   end
 
-  private
-
   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'

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+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
+    def descend(child_key)
+      self.class.new(
+        record: record, context: context, key: child_key,
+        path: path ? "#{path}.#{child_key}" : child_key.to_s,
+      )
+    end
+
+    def for_array_items
+      self.class.new(record: record, context: context, path: path, key: nil)
+    end
+  end
+  private_constant :BuildContext
+end