Fix Grape 3.2+ compatibility: desc kwargs, custom types, multi-type param recovery (#978)

Grape 3.2+ introduced breaking changes that raise when Grape.deprecator.behavior
= :raise: desc rejects a positional options Hash, params blocks reject string type
names and classes without .parse, and type: [A, B] params are serialised via
VariantCollectionCoercer#to_s, leaking the coercer's inspect string into swagger
output instead of the declared type.

- Pass keyword arguments to both desc calls in doc_methods.rb. Accept string-keyed
  api_documentation hashes and :description as an alias for :desc.

- Add .parse shims to NestedModule::ApiResponse in the mock and representable
  parsers. Move type: 'Object' in params_example_spec into documentation: {}.

- Recover the actual type list from VariantCollectionCoercer via
  stackable_values[:validations] in the Route param parser. Handles both the
  Hash-entry shape (Grape 3.2+) and the CoerceValidator object shape (older
  versions). Canary tests guard the private-ivar contract.

- Bump minimum Grape to >= 2.1 (1.8/2.0 fail on Ruby 3.3+ upstream) and expand
  upper bound to < 5.0 for Grape 4.x. Update CI matrix accordingly.

Author: numbata

.github/workflows/ci.yml

@@ -26,14 +26,6 @@ jobs:
     strategy:
       matrix:
         entry:
-          - { ruby: '3.1', grape: '1.8.0' }
-          - { ruby: '3.2', grape: '1.8.0' }
-          - { ruby: '3.3', grape: '1.8.0' }
-          - { ruby: '3.4', grape: '1.8.0' }
-          - { ruby: '3.1', grape: '2.0.0' }
-          - { ruby: '3.2', grape: '2.0.0' }
-          - { ruby: '3.3', grape: '2.0.0' }
-          - { ruby: '3.4', grape: '2.0.0' }
           - { ruby: '3.1', grape: '2.1.3' }
           - { ruby: '3.2', grape: '2.1.3' }
           - { ruby: '3.3', grape: '2.1.3' }
@@ -43,7 +35,9 @@ jobs:
           - { ruby: '3.3', grape: '2.2.0' }
           - { ruby: '3.4', grape: '2.2.0' }
           - { ruby: 'head', grape: '2.2.0' }
-          - { ruby: '3.2', grape: 'HEAD' }
+          - { ruby: '3.2', grape: '3.2.1' }
+          - { ruby: '3.3', grape: '3.2.1' }
+          - { ruby: '3.4', grape: '3.2.1' }
           - { ruby: '3.3', grape: 'HEAD' }
           - { ruby: '3.4', grape: 'HEAD' }
     name: test (ruby=${{ matrix.entry.ruby }}, grape=${{ matrix.entry.grape }})

.rubocop.yml

@@ -73,5 +73,8 @@ Style/RedundantArrayConstructor:
 Style/RegexpLiteral:
   Enabled: false
 
+Style/OneClassPerFile:
+  Enabled: false
+
 Style/SlicingWithRange:
   Enabled: false

.rubocop_todo.yml

@@ -21,7 +21,7 @@ Metrics/AbcSize:
 # Offense count: 32
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 28
+  Max: 30
 
 # Offense count: 9
 # Configuration parameters: AllowedMethods, AllowedPatterns.

CHANGELOG.md

@@ -1,11 +1,6 @@
-### 2.1.5 (Next)
-
-#### Features
-
-* Your contribution here.
-
-#### Fixes
+### 2.2.0 (Next)
 
+* [#978](https://github.com/ruby-grape/grape-swagger/pull/978): Fix Grape 3.2+ compatibility: desc kwargs, custom types, multi-type param recovery; bump Grape to `>= 2.1, < 5.0`. See [UPGRADING](UPGRADING.md) - [@numbata](https://github.com/numbata).
 * Your contribution here.
 
 ### 2.1.4 (2026-02-02)

Gemfile

@@ -29,6 +29,7 @@ group :development, :test do
   end
 
   gem 'cgi'
+  gem 'multi_json'
   gem 'rack-cors'
   gem 'rack-test'
   gem 'rake'

README.md

@@ -125,7 +125,8 @@ The following versions of grape, grape-entity and grape-swagger can currently be
 | >= 1.0.0              | 2.0          | >= 1.3.0                | >= 0.5.0     | >= 2.4.1      |
 | >= 2.0.0              | 2.0          | >= 1.7.0                | >= 0.5.0     | >= 2.4.1      |
 | >= 2.0.0 ... <= 2.1.2 | 2.0          | >= 1.8.0 ... < 2.3.0    | >= 0.5.0     | >= 2.4.1      |
-| > 2.1.2               | 2.0          | >= 1.8.0 ... < 4.0      | >= 0.5.0     | >= 2.4.1      |
+| >= 2.1.3 ... < 2.2.0  | 2.0          | >= 1.8.0 ... < 4.0      | >= 0.5.0     | >= 2.4.1      |
+| >= 2.2.0              | 2.0          | >= 2.1 ... < 5.0        | >= 0.5.0     | >= 2.4.1      |
 
 
 ## Swagger-Spec <a name="swagger-spec"></a>
@@ -498,6 +499,8 @@ add_swagger_documentation \
    api_documentation: { desc: 'Reticulated splines API swagger-compatible documentation.' }
 ```
 
+`:description` is accepted as an alias for `:desc` (when both are supplied, `:desc` wins; an explicit `desc: nil` is respected and does not fall through). String keys (e.g. when loading from YAML/JSON) are accepted too.
+
 #### specific_api_documentation
 
 Customize the Swagger API specific documentation route, typically contains a `desc` field. The default description is "Swagger compatible API description for specific API".

UPGRADING.md

@@ -1,5 +1,26 @@
 ## Upgrading Grape-swagger
 
+### Upgrading to >= 2.2.0
+
+- **Minimum Grape version is now `>= 2.1`** (was `>= 1.7`). Grape 1.8.0 and 2.0.0 cannot be used on Ruby 3.3+ because of an upstream Mustermann/forwardable incompatibility; the CI rows for those combinations were already failing on `master` and have been removed.
+- **`type: 'Object'` (and other string type names) in `params` blocks**: Grape 3.2+ rejects string type names. If you previously declared a swagger-only documentation hint via `params { optional :foo, type: 'Object' }`, move the type under `documentation:`:
+
+  ```ruby
+  optional :foo, documentation: { type: 'Object' }
+  ```
+
+  grape-swagger picks the type up from the merged settings unchanged, so the swagger output is identical.
+- **Custom type classes** used via `type: MyClass` must implement `MyClass.parse(value)` (arity 1) on Grape 3.2+; otherwise Grape's dry-types lookup raises `ArgumentError`. `Grape::Entity` already provides `parse`; `Representable::Decorator` and plain Ruby classes need to define it explicitly:
+
+  ```ruby
+  class MyType
+    def self.parse(value) = new(value)
+    # ...
+  end
+  ```
+
+- **Multi-type params (`type: [A, B]`) on Grape 3.2+**: swagger output now reflects the first declared type (e.g. `type: [Integer, Float]` produces `"integer"`). Previously, Grape 3.2+ serialized the `VariantCollectionCoercer` wrapper via `#to_s`, leaking `"#<Grape::Validations::Types::VariantCollectionCoercer:0x...>"` into the documentation. No action required, but if you were programmatically post-processing that string, the fix will change the output.
+
 ### Upgrading to >= x.y.z
 
 - Grape-swagger now documents array parameters within an object schema in Swagger. This aligns with grape's JSON structure requirements and ensures the documentation is correct.

grape-swagger.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |s|
   s.metadata['rubygems_mfa_required'] = 'true'
 
   s.required_ruby_version = '>= 3.1'
-  s.add_dependency 'grape', '>= 1.7', '< 4.0'
+  s.add_dependency 'grape', '>= 2.1', '< 5.0'
 
   s.files = Dir['lib/**/*', '*.md', 'LICENSE.txt', 'grape-swagger.gemspec']
   s.require_paths = ['lib']

lib/grape-swagger/doc_methods.rb

@@ -86,14 +86,16 @@ 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
+      # transform_keys normalizes string-keyed input, e.g. loaded from YAML/JSON.
+      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
+      # Only the named-resource endpoint extracts :params for its required route param below.
+      desc(pop_desc(api_doc), **api_doc)
 
       instance_eval(guard) unless guard.nil?
 
@@ -105,7 +107,9 @@ 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 }
+      specific_desc   = pop_desc(specific_api_doc)
+      specific_params = specific_api_doc.delete(:params) || {}
+      desc(specific_desc, params: specific_params, **specific_api_doc)
 
       params do
         requires :name, type: String, desc: 'Resource name of mounted API'
@@ -136,5 +140,15 @@ def setup_formatter(formatter)
 
       FORMATTER_METHOD.each { |method| send(method, formatter) }
     end
+
+    private
+
+    # explicit nil under :desc wins — don't fall through to :description
+    def pop_desc(doc)
+      result = doc.key?(:desc) ? doc.delete(:desc) : doc.delete(:description)
+      # Also remove the alias so it does not leak into **doc kwargs.
+      doc.delete(:description)
+      result
+    end
   end
 end

lib/grape-swagger/request_param_parsers/route.rb

@@ -19,8 +19,9 @@ def parse
         stackable_values = route.app&.inheritable_setting&.namespace_stackable
 
         path_params = build_path_params(stackable_values)
+        variant_types = collect_variant_types(stackable_values)
 
-        fulfill_params(path_params)
+        fulfill_params(path_params, variant_types)
       end
 
       private
@@ -47,7 +48,58 @@ def fetch_inherited_params(stackable_values)
         end
       end
 
-      def fulfill_params(path_params)
+      # Grape 3.2+ serializes `type: [A, B]` via VariantCollectionCoercer#to_s, losing the type list.
+      # Grape 3.2+ stores validator metadata as Hash entries; older supported versions use
+      # CoerceValidator object instances and require private-ivar reads below.
+      # If the internal structure changes in a future Grape version this silently returns {}.
+      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?(:[])
+
+        # StackableValues#[] concatenates this level and all inherited levels;
+        # no explicit chain walk is needed here.
+        (stackable_values[:validations] || []).each do |validator|
+          attrs, scope, converter = extract_variant_validator_parts(validator)
+          next unless attrs
+          next unless converter.is_a?(Grape::Validations::Types::VariantCollectionCoercer)
+
+          # TODO: use a public API once Grape exposes VariantCollectionCoercer#types.
+          types = converter.instance_variable_get(:@types).to_a
+          next if types.empty?
+
+          next unless scope.respond_to?(:full_name)
+
+          attrs.each do |attr|
+            # Key format must match param.to_s in restore_variant_type.
+            variant_types[scope.full_name(attr)] = types
+          end
+        end
+
+        variant_types
+      end
+
+      def extract_variant_validator_parts(validator)
+        if validator.is_a?(Hash)
+          return unless validator[:validator_class] == Grape::Validations::Validators::CoerceValidator
+
+          attrs = Array(validator[:attributes])
+          scope = validator[:params_scope]
+          converter = validator[:options].is_a?(Hash) ? validator[:options][:type] : nil
+          return [attrs, scope, converter]
+        end
+
+        return unless validator.is_a?(Grape::Validations::Validators::CoerceValidator)
+        return unless validator.respond_to?(:attrs)
+
+        attrs = Array(validator.attrs)
+        scope = validator.instance_variable_get(:@scope)
+        converter = validator.instance_variable_get(:@converter)
+        [attrs, scope, converter]
+      end
+
+      def fulfill_params(path_params, variant_types)
         # Merge path params options into route params
         route.params.each_with_object({}) do |(param, definition), accum|
           # The route.params hash includes both parametrized params (with a string as a key)
@@ -57,10 +109,18 @@ def fulfill_params(path_params)
           next if param.is_a?(String) && accum.key?(key)
 
           defined_options = definition.is_a?(Hash) ? definition : {}
+          defined_options = restore_variant_type(defined_options, param, variant_types)
           value = (path_params[param] || {}).merge(defined_options)
           accum[key] = value.empty? ? DEFAULT_PARAM_TYPE : value
         end
       end
+
+      def restore_variant_type(defined_options, param, variant_types)
+        types = variant_types[param.to_s]
+        return defined_options unless types
+
+        defined_options.merge(type: types)
+      end
     end
   end
 end