Tighten variant-type order, pop_desc nil semantics, document recovery scope

route.rb
- Convert the recovered VariantCollectionCoercer @types via #to_a so a
  Set-backed coercer yields a deterministic order (insertion order from
  the user's declaration), matching what `parse_multi_type` will pick
  via `.first` downstream.
- Guard scope.full_name with `respond_to?` so a future CoerceValidator
  built without @scope (custom subclasses, test doubles) degrades to
  skipping that validator rather than crashing the whole swagger doc
  generation with NoMethodError.
- Expand the leading comment to note that on Grape < 3.3 the recovery
  is a no-op (the legacy `"[A, B]"` string is already handled by
  parse_multi_type's regex branch), so a reader doesn't conclude the
  defined? guard is silently overriding working behaviour.

doc_methods.rb (pop_desc)
- Use `key?` instead of `||` so an explicit `desc: nil` is respected
  rather than silently falling through to `:description`. Document the
  precedence inline (`:desc` wins when both keys are supplied).

specs
- Cover the new public-facing `:desc`/`:description`/string-key
  semantics in api_documentation_spec so a future refactor can't
  regress them silently.

Author: numbata

lib/grape-swagger/doc_methods.rb

@@ -138,7 +138,9 @@ def setup_formatter(formatter)
     end
 
     def pop_desc(doc)
-      doc.delete(:desc) || doc.delete(:description)
+      # :desc takes precedence over :description; explicit nil under :desc wins
+      # (don't fall through on nil — that would silently substitute :description).
+      doc.key?(:desc) ? doc.delete(:desc) : doc.delete(:description)
     end
   end
 end

lib/grape-swagger/request_param_parsers/route.rb

@@ -48,12 +48,16 @@ def fetch_inherited_params(stackable_values)
         end
       end
 
-      # In Grape >= 3.3 `type: [A, B]` is wrapped in VariantCollectionCoercer and
-      # 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 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.
+      # On Grape >= 3.3 `type: [A, B]` is documented in route.params via the
+      # VariantCollectionCoercer's `#to_s`, which loses the original type list.
+      # On earlier versions the same param appears as the stringified Array
+      # `"[A, B]"` and the existing regex in DataType.parse_multi_type already
+      # handles it; the recovery here is a no-op for those versions.
+      #
+      # The live coercer is still reachable through the CoerceValidator's
+      # @converter, so we rebuild a name => types 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) &&
@@ -66,8 +70,12 @@ def collect_variant_types(stackable_values)
           converter = validator.instance_variable_get(:@converter)
           next unless converter.is_a?(Grape::Validations::Types::VariantCollectionCoercer)
 
-          types = Array(converter.instance_variable_get(:@types))
+          # `.to_a` preserves the user-declared order for both Array and Set
+          # storage shapes; `DataType.parse_multi_type` uses `.first` downstream.
+          types = converter.instance_variable_get(:@types).to_a
           scope = validator.instance_variable_get(:@scope)
+          next unless scope.respond_to?(:full_name)
+
           validator.attrs.each do |attr|
             variant_types[scope.full_name(attr)] = types
           end

spec/swagger_v2/api_documentation_spec.rb

@@ -23,4 +23,40 @@
       'Swagger compatible API description for specific API'
     ]
   end
+
+  context 'when api_documentation is string-keyed' do
+    let(:api) do
+      Class.new(Grape::API) do
+        add_swagger_documentation api_documentation: { 'desc' => 'String-keyed description' }
+      end
+    end
+
+    it 'accepts string keys' do
+      expect(subject.first[:description]).to eq('String-keyed description')
+    end
+  end
+
+  context 'when api_documentation uses :description instead of :desc' do
+    let(:api) do
+      Class.new(Grape::API) do
+        add_swagger_documentation api_documentation: { description: 'Via description key' }
+      end
+    end
+
+    it 'falls back to :description' do
+      expect(subject.first[:description]).to eq('Via description key')
+    end
+  end
+
+  context 'when both :desc and :description are supplied' do
+    let(:api) do
+      Class.new(Grape::API) do
+        add_swagger_documentation api_documentation: { desc: 'Desc wins', description: 'Description loses' }
+      end
+    end
+
+    it ':desc takes precedence' do
+      expect(subject.first[:description]).to eq('Desc wins')
+    end
+  end
 end