[ruby] fix: explode object query parameters

[wiebren]

A query parameter whose schema is an object and whose style/explode are left at their
defaults — style: form, explode: true — must go on the wire as one parameter per entry,
keyed by the property name alone. The ruby client assigned the whole hash under the
parameter name and left the http library to serialize it, which comes out in rails bracket
style, while csharp, java and php got it right.

Given:

parameters:
  - in: query
    name: filter
    schema:
      type: object

called with {"tld": "com", "createdDate:gte": "2023-01-01"}:

generator	on the wire
expected	tld=com&createdDate%3Agte=2023-01-01
ruby	filter%5Btld%5D=com&filter%5BcreatedDate%3Agte%5D=2023-01-01
csharp, java, php	correct

Sibling of #24797 (go), #24802 (python) and #24803 (typescript-fetch), one PR per language
per the maintainer's request on #24797. This PR is independent of the other three — no
shared main/ code. It adds the same test fixture at the same path with identical content,
so whichever lands first, the others rebase cleanly.

The cause

ruby-client/api.mustache — the generated api put the hash into query_params whole
(query_params[:'filter'] = opts[:'filter']), and no style or explode ever reaches the
runtime: typhoeus, faraday and httpx all encode a nested hash in bracket style.

The fix merges an exploded map into query_params entry by entry at the call site —

opts[:'filter'].each { |name, value| query_params[name.to_s] = value } if !opts[:'filter'].nil?

— which fixes all three http libraries at once, since they all consume the query_params
hash the api builds. deepObject and explode: false parameters keep the exact line they
produced before, and so does every other parameter shape (build_collection_param for
arrays, to_json for json-content parameters).

Exploded entries use string keys where spec-declared parameters use symbol keys, so an entry
whose name collides with a declared sibling parameter does not overwrite it — both go on the
wire. There is no equivalent of the python collection-format lookup here
(build_collection_param is only ever emitted for declared array parameters), so the
runtime-name collision that bit #24802 has no ruby counterpart.

Verified on the wire, not just asserted

The client was generated from the new fixture and pointed at a server that echoes its own raw
request line back (typhoeus, the default library):

parameter	before	after
filter (object, defaults)	filter%5Btld%5D=com&filter%5BcreatedDate%3Agte%5D=2023-01-01	tld=com&createdDate%3Agte=2023-01-01
typedFilter (map, defaults)	same bracket shape	tld=com&createdDate%3Agte=2023-01-01
deepFilter (style: deepObject)	deepFilter%5Btld%5D=com&…	unchanged, byte for byte
flatFilter (explode: false)	flatFilter%5Btld%5D=com&…	unchanged, byte for byte

The deepFilter row is worth a note: the accidental bracket encoding is the declared
deepObject format, so deepObject parameters were already correct here and stay untouched.

Known gaps, called out deliberately

explode: false keeps its previous bracket encoding. The spec asks for
flatFilter=tld,com,createdDate:gte,2023-01-01; it was bracketed before and is bracketed
after, byte for byte — same scoping as the sibling PRs, left for a follow-up to keep this
reviewable.

Declared object models. A $refed object model as a query parameter is isModel, not
isMap, so it still goes on the wire whole. Pre-existing, and the same gap the sibling PRs
document. Left for a follow-up.

Tests

modules/openapi-generator/src/test/resources/3_0/exploded-object-query-param.yaml covers
the four combinations that decide the wire format:

• RubyClientCodegenTest#testExplodedObjectQueryParameter

It fails without the fix (verified by stashing only the template change). All 26 tests in
RubyClientCodegenTest pass.

PR checklist

• Read the contribution guidelines.
• Built the project and updated samples (./bin/generate-samples.sh for
  bin/configs/ruby*.yaml; ./bin/utils/export_docs_generators.sh produced no diff).
  4 sample files changed, all fake_api.rb (ruby, ruby-autoload, ruby-faraday,
  ruby-httpx), from the petstore fixture's language parameter — a declared map with the
  default style, the same parameter that changed in the python sibling.
• Technical committee: @meganemura @dkliban @HoneyryderChuck

---

Generated with Claude Code

---

Summary by cubic

Fixes the Ruby client generator so object query parameters with default style: form and explode: true go on the wire as one parameter per entry, keyed by the property name alone, instead of the whole hash under the parameter name (which produced bracket-style encoding like filter[tld]=com).

Notes

• deepObject and explode: false parameters keep their previous wire format, byte for byte.
• explode: false and $refed object models still serialize the old way; aligning them with the spec is left for follow-ups.
• The fix covers typhoeus, faraday, and httpx alike, since they all consume the query_params hash the generated api builds.
• Adds a test fixture for the four style/explode combinations; the test fails without the template change.

^{Written for commit cd9d7a5. Summary will update on new commits.}

[cubic-dev-ai]

2 issues found across 7 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="samples/client/petstore/ruby-faraday/lib/petstore/api/fake_api.rb">

<violation number="1" location="samples/client/petstore/ruby-faraday/lib/petstore/api/fake_api.rb:1575">
P3: The exploded entries use string keys (`query_params[name.to_s]`), while every other declared parameter in this method is set with a symbol key (`query_params[:'pipe']`, `query_params[:'context']`, etc.). Because Ruby treats `:"pipe"` and `"pipe"` as distinct hash keys, a `language` map entry whose name collides with a declared parameter is not overwritten as the PR description claims - it is serialized in addition to the declared parameter, producing two same-named query parameters on the wire (e.g. the array `context` plus `context=<string>`). Use the same key namespace or document the collision behavior; mixing symbol-keyed declared params with string-keyed exploded parts makes the "no overwriting" guarantee produce ambiguous duplicate params instead.</violation>
</file>

<file name="modules/openapi-generator/src/main/resources/ruby-client/api.mustache">

<violation number="1" location="modules/openapi-generator/src/main/resources/ruby-client/api.mustache:187">
P3: The PR description claims exploded-map collisions with other declared parameters are "handled without overwriting", but `query_params[name.to_s] = value` is a plain hash assignment that overwrites any existing entry. If a map key equals another declared query parameter's name, the value depends purely on parameter ordering in the generated method and the earlier entry is silently dropped. Either drop the collision claim or guard the assignment (e.g. `query_params[name.to_s] = value unless query_params.key?(name.to_s)`), keeping the explicit map entries from clobbering declared parameters.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: The exploded entries use string keys (query_params[name.to_s]), while every other declared parameter in this method is set with a symbol key (query_params[:'pipe'], query_params[:'context'], etc.). Because Ruby treats :"pipe" and "pipe" as distinct hash keys, a language map entry whose name collides with a declared parameter is not overwritten as the PR description claims - it is serialized in addition to the declared parameter, producing two same-named query parameters on the wire (e.g. the array context plus context=<string>). Use the same key namespace or document the collision behavior; mixing symbol-keyed declared params with string-keyed exploded parts makes the "no overwriting" guarantee produce ambiguous duplicate params instead.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/petstore/ruby-faraday/lib/petstore/api/fake_api.rb, line 1575:

<comment>The exploded entries use string keys (`query_params[name.to_s]`), while every other declared parameter in this method is set with a symbol key (`query_params[:'pipe']`, `query_params[:'context']`, etc.). Because Ruby treats `:"pipe"` and `"pipe"` as distinct hash keys, a `language` map entry whose name collides with a declared parameter is not overwritten as the PR description claims - it is serialized in addition to the declared parameter, producing two same-named query parameters on the wire (e.g. the array `context` plus `context=<string>`). Use the same key namespace or document the collision behavior; mixing symbol-keyed declared params with string-keyed exploded parts makes the "no overwriting" guarantee produce ambiguous duplicate params instead.</comment>

<file context>
@@ -1571,7 +1571,8 @@ def test_query_parameter_collection_format_with_http_info(pipe, ioutil, http, ur
       query_params[:'allowEmpty'] = allow_empty
-      query_params[:'language'] = opts[:'language'] if !opts[:'language'].nil?
+      # form style explodes an object into one query parameter per entry, keyed by the property name alone
+      opts[:'language'].each { |name, value| query_params[name.to_s] = value } if !opts[:'language'].nil?
 
       # header parameters
</file context>

[cubic-dev-ai]

P3: The PR description claims exploded-map collisions with other declared parameters are "handled without overwriting", but query_params[name.to_s] = value is a plain hash assignment that overwrites any existing entry. If a map key equals another declared query parameter's name, the value depends purely on parameter ordering in the generated method and the earlier entry is silently dropped. Either drop the collision claim or guard the assignment (e.g. query_params[name.to_s] = value unless query_params.key?(name.to_s)), keeping the explicit map entries from clobbering declared parameters.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At modules/openapi-generator/src/main/resources/ruby-client/api.mustache, line 187:

<comment>The PR description claims exploded-map collisions with other declared parameters are "handled without overwriting", but `query_params[name.to_s] = value` is a plain hash assignment that overwrites any existing entry. If a map key equals another declared query parameter's name, the value depends purely on parameter ordering in the generated method and the earlier entry is silently dropped. Either drop the collision claim or guard the assignment (e.g. `query_params[name.to_s] = value unless query_params.key?(name.to_s)`), keeping the explicit map entries from clobbering declared parameters.</comment>

<file context>
@@ -180,7 +180,23 @@ module {{moduleName}}
+      {{#isExplode}}
+      {{^isDeepObject}}
+      # form style explodes an object into one query parameter per entry, keyed by the property name alone
+      {{{paramName}}}.each { |name, value| query_params[name.to_s] = value }
+      {{/isDeepObject}}
+      {{#isDeepObject}}
</file context>