[olivier-thatch]

Fixes #952.

Summary

Sharing array parameters between GET and POST/PUT/PATCH endpoints no longer drops them from the generated body definition when array_use_braces is on. Nested arrays such as Array[Array[String]] are now documented with every level instead of being flattened to a single array of strings.

Root cause

With array_use_braces: true, RequestParamParsers::Body#parse appends [] to every array param name. It runs before the param's location is known, because that depends on the HTTP method and consumes. Params that become body params (any non-GET without an explicit param_type) kept the braced name, so the body definition got a bogus property or lost the array. The parser also adds the braced copy next to the original, so after renaming, the two collide and the copy was merged over the group's object definition (items.type object became string).

Changes

• ParseParams strips the [] suffix for array params that end up in the body.
• params_object drops duplicates by [name, in] before moving params into a body definition. This also removes the duplicate required entries, so the uniq! suggested earlier is no longer needed.
• Array items are wrapped in one array level per nesting (Array[Array[String]] becomes an array of array of string).

Drawbacks

• The brace is still added in Body#parse and removed later in ParseParams. This is a patch over a decision made too early; see below.
• Output changes for anyone who already declared nested arrays: items used to be flattened and now has the inner array. Nested arrays in query/formData params are documented the same way, which is valid in the Swagger 2.0 items schema but unusual for a query string.

Rejected alternatives

• Not adding the brace in Body#parse: the param's in isn't known there (it depends on method and consumes), so it would need a larger refactor.
• Set for definition[:required]: changes the interface that other grape-swagger-* gems rely on (Set has no push).
• Keeping uniq! on required: it only hid the duplicate params.

Not covered

Array[JSON] and JSON params still document type: "json", which is not a Swagger type. That is unrelated to array_use_braces and tracked in #1014.

[dblock]

CI was fixed in #958, rebase please?

[numbata]

Hi @olivier-thatch, a quick fix for this PR could be:

diff --git a/lib/grape-swagger/doc_methods/move_params.rb b/lib/grape-swagger/doc_methods/move_params.rb
index c8417ce..12c6477 100644
--- a/lib/grape-swagger/doc_methods/move_params.rb
+++ b/lib/grape-swagger/doc_methods/move_params.rb
@@ -136,7 +136,7 @@ module GrapeSwagger
           return if value.blank?
 
           definition[:required] ||= []
-          definition[:required].push(*value)
+          definition[:required].push(*value).uniq!
         end
 
         def build_body_parameter(name, options)

I considered using a Set.new for definition[:required] to enforce uniqueness, but that would change the interface (as example, Set doesn’t support .push) and could introduce side effects for other grape-swagger-* gems.

[numbata]

I looked more closely at the PR and noticed we have incorrect behavior for nested arrays. The type Array[Array[String]] collapses into String, so document_array_param only ever sees one dimension. As a result, a declaration like
requires :matrix, type: Array[Array[String]]
produces { type: 'array', items: { type: 'string' } }, which loses the inner array.

We need to either fix this to properly support multi-dimensional arrays or clearly document that they aren’t supported.

[github-actions]

Danger Report

No issues found.

View run

[Copilot]

🟡 Changes recommended

A critical defect leaves deeply nested array schemas with invalid inner item types because array declarations are only unwrapped one level instead of being recursively normalized.

1 open issue

• Recursively unwrap nested array types before generating item schemas · New

What changed in this PR

This pull request fixes omitted array parameters when array_use_braces is enabled and preserves nested array structure in generated Swagger 2.0 schemas.

Changes:

• Removes trailing [] from array parameters converted to request-body properties.
• Deduplicates parameters before body-definition generation.
• Adds nested-array schema handling and regression coverage.
• Updates the changelog.

The nested-array implementation still produces invalid leaf item types for declarations such as Array[Array[String]]; recursive type normalization is required before approval.

This pull request requires changes.

File	Description
spec/​swagger_v2/​params_array_spec.rb	Adds regression coverage for body, query, form, shared, and nested array parameters.
lib/​grape-swagger/​endpoint.rb	Deduplicates parameters by name and location before moving body parameters into definitions.
lib/​grape-swagger/​doc_methods/​parse_params.rb	Normalizes body array names and attempts to preserve nested array structure; nested leaf types require recursive normalization.
CHANGELOG.md	Documents the array-parameter and nested-array fixes.

_{Review effort: Lite}