Address review findings: scope-aware variant keys, robust desc kwargs

VariantCollectionCoercer recovery (route.rb)
- Build the variant-type map keyed by the fully-qualified param name
  (e.g. "group[inner]") via the validator's @scope.full_name(attr), so
  nested-param multi-types are restored instead of being looked up under
  the wrong key, and same-named outer params at a different scope are not
  clobbered.
- Use the public validator.attrs reader, and normalise the recovered
  @types to an Array so an order-defined coercer Set cannot leak in.
- Cover the inheritance shape of stackable[:validations] with .flatten.

desc keyword-args (doc_methods.rb)
- Coerce api_documentation / specific_api_documentation keys to symbols
  via transform_keys before splatting, so string-keyed Hashes (YAML/JSON
  configs) no longer raise TypeError under `**`.
- Accept :description as an alias for :desc. Without this, a user-supplied
  :description was forwarded into Grape's desc and immediately overwritten
  with nil because the positional description arg was missing.

Tests
- Add a regression spec asserting `type: [Integer, Float]` produces
  "integer" (the only assertion that proves the recovery actually wires
  the real types through; previously [String, Integer] also "worked" via
  the broken fallback because String happens to be first).
- Cover the nested-namespace case (`group { requires :inner, type: [...] }`)
  to lock in the scope-aware key.

CHANGELOG
- Document the >= 2.1 Grape floor bump and the `type: 'Object'` migration
  pattern under a Breaking changes section, and split the multi-type
  recovery and desc-kwargs robustness fixes into separate entries.

Author: numbata

CHANGELOG.md

@@ -4,9 +4,16 @@
 
 * Your contribution here.
 
+#### Breaking changes
+
+* Minimum required Grape version is now `>= 2.1` (was `>= 1.7`). Grape 1.8.0 and 2.0.0 do not work on Ruby 3.3+ due to a Mustermann private-method incompatibility (the existing CI rows for those versions had been failing on master). Their CI rows are removed.
+* On Grape 3.2+ the `params` block rejects string type names. If you used `params { optional :foo, type: 'Object' }` to declare a swagger-only documentation hint, move the type into the `documentation:` hash: `optional :foo, documentation: { type: 'Object' }`. grape-swagger picks the type up from the merged settings unchanged.
+
 #### Fixes
 
 * [#977](https://github.com/ruby-grape/grape-swagger/issues/977): Pass keyword arguments to `desc` to fix deprecation warning from Grape - [@numbata](https://github.com/numbata).
+* Accept string-keyed `api_documentation` / `specific_api_documentation` and the `:description` key as an alias for `:desc`, matching the pre-keyword-args behaviour of `desc`.
+* Grape 3.3+: recover the real type list for multi-type params (`type: [A, B]`). Grape now wraps these in a `VariantCollectionCoercer` and serialises it via `#to_s` in `route.params`, which lost the original types. Swagger output now reflects the first declared type (e.g. `type: [Integer, Float]` produces `"integer"`) instead of the coercer's `#inspect` string.
 
 ### 2.1.4 (2026-02-02)
 

lib/grape-swagger/doc_methods.rb

@@ -86,14 +86,14 @@ def setup(options)
       # for available options see #defaults
       target_class     = options[:target_class]
       guard            = options[:swagger_endpoint_guard]
-      api_doc          = options[:api_documentation].dup
-      specific_api_doc = options[:specific_api_documentation].dup
+      api_doc          = options[:api_documentation].transform_keys(&:to_sym)
+      specific_api_doc = options[:specific_api_documentation].transform_keys(&:to_sym)
 
       class_variables_from(options)
 
       setup_formatter(options[:format])
 
-      desc api_doc.delete(:desc), **api_doc
+      desc(pop_desc(api_doc), **api_doc)
 
       instance_eval(guard) unless guard.nil?
 
@@ -105,7 +105,7 @@ def setup(options)
           .output_path_definitions(target_class.combined_namespace_routes, self, target_class, options)
       end
 
-      desc specific_api_doc.delete(:desc), params: specific_api_doc.delete(:params) || {}, **specific_api_doc
+      desc(pop_desc(specific_api_doc), params: specific_api_doc.delete(:params) || {}, **specific_api_doc)
 
       params do
         requires :name, type: String, desc: 'Resource name of mounted API'
@@ -136,5 +136,9 @@ def setup_formatter(formatter)
 
       FORMATTER_METHOD.each { |method| send(method, formatter) }
     end
+
+    def pop_desc(doc)
+      doc.delete(:desc) || doc.delete(:description)
+    end
   end
 end

lib/grape-swagger/request_param_parsers/route.rb

@@ -52,22 +52,24 @@ def fetch_inherited_params(stackable_values)
       # Grape's documentation pipeline serialises it via `#to_s`, so the original
       # type list is lost in route.params. The live coercer is still reachable
       # through the CoerceValidator's @converter, so we rebuild a name => types
-      # map and restore it in fulfill_params.
+      # map keyed by the fully-qualified param name (e.g. "group[inner]") to match
+      # route.params keys and avoid clobbering same-named params at outer scopes.
       def collect_variant_types(stackable_values)
         variant_types = {}
         return variant_types unless defined?(Grape::Validations::Types::VariantCollectionCoercer) &&
                                     defined?(Grape::Validations::Validators::CoerceValidator) &&
                                     stackable_values.respond_to?(:[])
 
-        Array(stackable_values[:validations]).each do |validator|
+        Array(stackable_values[:validations]).flatten.each do |validator|
           next unless validator.is_a?(Grape::Validations::Validators::CoerceValidator)
 
           converter = validator.instance_variable_get(:@converter)
           next unless converter.is_a?(Grape::Validations::Types::VariantCollectionCoercer)
 
-          types = converter.instance_variable_get(:@types)
-          Array(validator.instance_variable_get(:@attrs)).each do |attr|
-            variant_types[attr.to_s] = types
+          types = Array(converter.instance_variable_get(:@types))
+          scope = validator.instance_variable_get(:@scope)
+          validator.attrs.each do |attr|
+            variant_types[scope.full_name(attr)] = types
           end
         end
 

spec/swagger_v2/param_multi_type_spec.rb

@@ -50,6 +50,35 @@ def app
     ]
   end
 
+  describe 'with non-string primary type' do
+    def app
+      Class.new(Grape::API) do
+        format :json
+
+        desc 'action' do
+          consumes ['application/x-www-form-urlencoded']
+        end
+        params do
+          requires :int_first, type: [Integer, Float]
+          requires :nested_group, type: Hash do
+            requires :nested_int, type: [Integer, Float]
+          end
+        end
+        post :action do
+          { message: 'hi' }
+        end
+
+        add_swagger_documentation
+      end
+    end
+
+    it 'recovers the first variant type, not a hardcoded fallback' do
+      types = subject.to_h { |p| [p['name'], p['type']] }
+      expect(types['int_first']).to eq('integer')
+      expect(types['nested_group[nested_int]']).to eq('integer')
+    end
+  end
+
   describe 'header params' do
     def app
       Class.new(Grape::API) do