rspec-openapi 0.25.1 → 0.27.0

data/lib/rspec/openapi/schema_cleaner.rb

@@ -27,7 +27,7 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
     cleanup_hash!(base, spec, 'paths.*.*')
 
     # cleanup parameters
-    cleanup_array!(base, spec, 'paths.*.*.parameters', %i[name in])
+    cleanup_array!(base, spec, 'paths.*.*.parameters', [:name, :in])
 
     # cleanup requestBody
     cleanup_hash!(base, spec, 'paths.*.*.requestBody.content.application/json.schema.properties.*')
@@ -86,6 +86,9 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
     hash.delete(:_example_key)
     hash.delete(:_example_summary)
     hash.delete(:_example_name)
+    if (fallback = hash.delete(:_fallback_description))
+      hash[:description] ||= fallback
+    end
 
     hash.each_value do |value|
       case value

data/lib/rspec/openapi/schema_file.rb

@@ -27,12 +27,10 @@ class RSpec::OpenAPI::SchemaFile
   def read
     return {} unless File.exist?(@path)
 
-    RSpec::OpenAPI::KeyTransformer.symbolize(
-      YAML.safe_load(
-        File.read(@path),
-        permitted_classes: [Date, Time],
-      ),
-    ) # this can also parse JSON
+    content = YAML.safe_load(File.read(@path), permitted_classes: [Date, Time]) # this can also parse JSON
+    return {} if content.nil?
+
+    RSpec::OpenAPI::KeyTransformer.symbolize(content)
   end
 
   # @param [Hash] spec

data/lib/rspec/openapi/schema_merger.rb

@@ -25,28 +25,53 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
       return base
     end
 
-    spec.each do |key, value|
-      if base[key].is_a?(Hash) && value.is_a?(Hash)
-        # Handle example/examples conflict - convert to examples when mixed
-        normalize_example_fields!(base[key], value)
-
-        # If the new value has oneOf, replace the entire value instead of merging
-        if value.key?(:oneOf)
-          base[key] = value
-        else
-          merge_schema!(base[key], value) unless base[key].key?(:$ref)
-        end
-      elsif base[key].is_a?(Array) && value.is_a?(Array)
-        # parameters need to be merged as if `name` and `in` were the Hash keys.
-        merge_arrays(base, key, value)
-      else
-        # do not ADD `properties` or `required` fields if `additionalProperties` field is present
-        base[key] = value unless base.key?(:additionalProperties) && %i[properties required].include?(key)
-      end
-    end
+    prune_stale_object_fields!(base, spec)
+
+    spec.each { |key, value| merge_entry!(base, key, value) }
     base
   end
 
+  # When the new spec converts an object to a dictionary (introduces
+  # `additionalProperties` on a node that previously had `properties` /
+  # `required`), drop the stale fields so the merged result reflects the
+  # new intent. We only prune when base does not already declare
+  # `additionalProperties`, to preserve manual edits that intentionally
+  # combine fixed and dynamic keys.
+  def prune_stale_object_fields!(base, spec)
+    return unless spec.is_a?(Hash) && spec.key?(:additionalProperties) && !base.key?(:additionalProperties)
+
+    base.delete(:properties)
+    base.delete(:required)
+  end
+
+  def merge_entry!(base, key, value)
+    if base[key].is_a?(Hash) && value.is_a?(Hash)
+      merge_hash_entry!(base, key, value)
+    elsif base[key].is_a?(Array) && value.is_a?(Array)
+      # parameters need to be merged as if `name` and `in` were the Hash keys.
+      merge_arrays(base, key, value)
+    elsif !skip_due_to_additional_properties?(base, key)
+      base[key] = value
+    end
+  end
+
+  def merge_hash_entry!(base, key, value)
+    # Handle example/examples conflict - convert to examples when mixed
+    normalize_example_fields!(base[key], value)
+
+    # If the new value has oneOf, replace the entire value instead of merging
+    if value.key?(:oneOf)
+      base[key] = value
+    elsif !base[key].key?(:$ref)
+      merge_schema!(base[key], value)
+    end
+  end
+
+  # do not ADD `properties` or `required` fields if `additionalProperties` field is present
+  def skip_due_to_additional_properties?(base, key)
+    base.key?(:additionalProperties) && [:properties, :required].include?(key)
+  end
+
   def merge_arrays(base, key, value)
     base[key] = case key
                 when :parameters
@@ -61,21 +86,33 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
   end
 
   def merge_parameters(base, key, value)
-    all_parameters = value | base[key]
-
-    unique_base_parameters = build_unique_params(base, key)
-
-    all_parameters = all_parameters.map do |parameter|
-      base_parameter = unique_base_parameters[[parameter[:name], parameter[:in]]] || {}
-      if base_parameter.empty?
-        parameter
+    base_params = index_parameters_by_identity(base[key])
+    new_params = index_parameters_by_identity(value)
+
+    base[key] = (base_params.keys | new_params.keys).map do |param_key|
+      base_param = base_params[param_key]
+      new_param = new_params[param_key]
+
+      if base_param && new_param
+        merge_parameter_with_schema(base_param, new_param)
+      elsif new_param
+        # Parameter only in the new spec. Treat as optional unless its `required: true`
+        # came from explicit `required_request_params` metadata — distinguishable only
+        # for `query`, where the schema_builder default is `required: false`. `header`
+        # defaults to `required: true`, so the value alone can't signal user intent.
+        new_param[:in] == 'query' && new_param[:required] ? new_param : mark_optional_unless_path(new_param)
       else
-        merge_parameter_with_schema(base_parameter, parameter)
+        mark_optional_unless_path(base_param)
       end
     end
+  end
+
+  # OpenAPI requires `in: path` parameters to be `required: true`, so this leaves
+  # them untouched.
+  def mark_optional_unless_path(parameter)
+    return parameter if parameter[:in] == 'path'
 
-    all_parameters.uniq! { |param| param.slice(:name, :in) }
-    base[key] = all_parameters
+    parameter.merge(required: false)
   end
 
   def merge_parameter_with_schema(base_param, new_param)
@@ -83,12 +120,18 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
     new_schema = new_param[:schema]
 
     # If schemas have different types, create a oneOf
-    if base_schema && new_schema && schemas_have_different_types?(base_schema, new_schema)
-      merged_schema = merge_schemas_into_one_of(base_schema, new_schema)
-      base_param.merge(new_param).merge(schema: merged_schema)
-    else
-      base_param.merge(new_param)
-    end
+    merged = if base_schema && new_schema && schemas_have_different_types?(base_schema, new_schema)
+               merged_schema = merge_schemas_into_one_of(base_schema, new_schema)
+               base_param.merge(new_param).merge(schema: merged_schema)
+             else
+               base_param.merge(new_param)
+             end
+
+    # Once a parameter has been seen missing in any earlier test case, keep it optional
+    # even if later test cases mark it required again.
+    merged = mark_optional_unless_path(merged) if base_param[:required] == false || new_param[:required] == false
+
+    merged
   end
 
   def schemas_have_different_types?(schema1, schema2)
@@ -122,10 +165,8 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
     end
   end
 
-  def build_unique_params(base, key)
-    base[key].to_h do |parameter|
-      [[parameter[:name], parameter[:in]], parameter]
-    end
+  def index_parameters_by_identity(parameters)
+    parameters.to_h { |p| [[p[:name], p[:in]], p] }
   end
 
   # Normalize example/examples fields when there's a conflict

data/lib/rspec/openapi/version.rb

@@ -2,6 +2,6 @@
 
 module RSpec
   module OpenAPI
-    VERSION = '0.25.1'
+    VERSION = '0.27.0'
   end
 end

data/lib/rspec/openapi.rb

@@ -43,10 +43,10 @@ module RSpec::OpenAPI
   @request_headers = []
   @servers = []
   @security_schemes = []
-  @example_types = %i[request]
+  @example_types = [:request]
   @response_headers = []
   @path_records = Hash.new { |h, k| h[k] = [] }
-  @ignored_path_params = %i[controller action format]
+  @ignored_path_params = [:controller, :action, :format]
   @ignored_paths = []
   @post_process_hook = nil
 

data/redocly.yaml

@@ -0,0 +1,31 @@
+# Config for `redocly lint` used by .github/workflows/validate-openapi.yml
+# to validate test-fixture OpenAPI documents shipped under spec/apps/.
+#
+# spec/apps/rails/doc/smart/openapi.yaml is intentionally excluded:
+# it is the input fixture for the smart-merge feature test (it contains
+# unresolved $refs by design), not a complete API description.
+extends:
+  - minimal
+apis:
+  rails-rspec-yaml:
+    root: spec/apps/rails/doc/rspec_openapi.yaml
+  rails-rspec-json:
+    root: spec/apps/rails/doc/rspec_openapi.json
+  rails-minitest-yaml:
+    root: spec/apps/rails/doc/minitest_openapi.yaml
+  rails-minitest-json:
+    root: spec/apps/rails/doc/minitest_openapi.json
+  rails-smart-expected:
+    root: spec/apps/rails/doc/smart/expected.yaml
+  roda-rspec-yaml:
+    root: spec/apps/roda/doc/rspec_openapi.yaml
+  roda-rspec-json:
+    root: spec/apps/roda/doc/rspec_openapi.json
+  roda-minitest-yaml:
+    root: spec/apps/roda/doc/minitest_openapi.yaml
+  roda-minitest-json:
+    root: spec/apps/roda/doc/minitest_openapi.json
+  hanami-yaml:
+    root: spec/apps/hanami/doc/openapi.yaml
+  hanami-json:
+    root: spec/apps/hanami/doc/openapi.json

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-openapi
 version: !ruby/object:Gem::Version
-  version: 0.25.1
+  version: 0.27.0
 platform: ruby
 authors:
 - Takashi Kokubun
@@ -67,6 +67,7 @@ files:
 - ".github/workflows/publish.yml"
 - ".github/workflows/rubocop.yml"
 - ".github/workflows/test.yml"
+- ".github/workflows/validate-openapi.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
@@ -96,12 +97,14 @@ files:
 - lib/rspec/openapi/result_recorder.rb
 - lib/rspec/openapi/rspec_hooks.rb
 - lib/rspec/openapi/schema_builder.rb
+- lib/rspec/openapi/schema_builder/build_context.rb
 - lib/rspec/openapi/schema_cleaner.rb
 - lib/rspec/openapi/schema_file.rb
 - lib/rspec/openapi/schema_merger.rb
 - lib/rspec/openapi/schema_sorter.rb
 - lib/rspec/openapi/shared_hooks.rb
 - lib/rspec/openapi/version.rb
+- redocly.yaml
 - rspec-openapi.gemspec
 - scripts/rspec
 - scripts/rspec_with_simplecov
@@ -112,7 +115,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.25.1
+  changelog_uri: https://github.com/exoego/rspec-openapi/releases/tag/v0.27.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -128,7 +131,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Generate OpenAPI schema from RSpec request specs
 test_files: []