[dart] fix: explode object query parameters (#24868)

* fix: [dart] explode object query parameters

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 dart client handed
the whole map to _queryParams, which stringified it with Map.toString() into a
single parameter (filter={tld: com, createdDate:gte: 2023-01-01}).

The generated api now iterates an exploded map entry by entry at the call
site; _queryParams is left alone, since it never receives style or explode
and is still the right fallback for every other parameter. A free-form
object is typed Object in dart and needs a cast to Map; a declared map does
not. deepObject and explode: false objects keep their previous wire format,
byte for byte.

The new test fixture covers the four style/explode combinations that decide
the wire format; the test fails without the template change.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CxDNCjqJycKTfzVWg2SeTJ

* fix: [dart] repeat the key per element for a collection in an exploded object

An exploded form-style object query parameter handed each entry to
_queryParams with an empty collection format, which defaults to csv, so a
list value went out comma joined (tld=com%2Cnet) instead of once per element
(tld=com&tld=net). A Set went out as its toString(), since _queryParams only
expands a List, and a null element went out as an empty value.

Each entry is now passed with the 'multi' collection format, and an Iterable
value is turned into a List with its null elements dropped first, so the key
repeats once per non-null element and an empty collection adds nothing. The
closure parameter is typed dynamic so the Iterable check still compiles for a
map with a declared value type.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* chore: [dart] trim the exploded query comment

The shipped comment is one line now, without the implementation note.
Fix the fixture description, which claimed four style/explode
combinations where it covers three, and retitle the test.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* test: [dart] keep the shared fixture byte-identical with the other ports

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: wiebren

modules/openapi-generator/src/main/resources/dart2/api.mustache

@@ -67,7 +67,23 @@ class {{{classname}}} {
         {{^required}}
     if ({{{paramName}}} != null) {
           {{/required}}
+        {{#isMap}}
+          {{#isExplode}}
+            {{^isDeepObject}}
+      // form style, explode: one query parameter per entry, keyed by the property name; a collection repeats the key per non-null element
+      {{#isFreeFormObject}}({{{paramName}}} as Map){{/isFreeFormObject}}{{^isFreeFormObject}}{{{paramName}}}{{/isFreeFormObject}}.forEach((entryKey, dynamic entryValue) => queryParams.addAll(_queryParams('multi', entryKey.toString(), entryValue is Iterable ? entryValue.where((e) => e != null).toList() : entryValue)));
+            {{/isDeepObject}}
+            {{#isDeepObject}}
       queryParams.addAll(_queryParams('{{{collectionFormat}}}', '{{{baseName}}}', {{{paramName}}}));
+            {{/isDeepObject}}
+          {{/isExplode}}
+          {{^isExplode}}
+      queryParams.addAll(_queryParams('{{{collectionFormat}}}', '{{{baseName}}}', {{{paramName}}}));
+          {{/isExplode}}
+        {{/isMap}}
+        {{^isMap}}
+      queryParams.addAll(_queryParams('{{{collectionFormat}}}', '{{{baseName}}}', {{{paramName}}}));
+        {{/isMap}}
           {{^required}}
     }
         {{/required}}

modules/openapi-generator/src/test/java/org/openapitools/codegen/dart/DartClientCodegenTest.java

@@ -137,6 +137,34 @@ public void testObjectArrayDoesNotUseListFromJson() throws Exception {
         TestUtils.assertFileContains(modelFile.toPath(), "cast<Object>");
     }
 
+    @Test(description = "Verify a form style, exploded map query parameter goes on the wire one entry per parameter")
+    public void testExplodedObjectQueryParameter() throws Exception {
+        List<File> files = generateDartNativeFromSpec(
+                "src/test/resources/3_0/exploded-object-query-param.yaml");
+
+        File apiFile = files.stream()
+                .filter(f -> f.getName().equals("default_api.dart"))
+                .findFirst()
+                .orElseThrow(() -> new AssertionError("default_api.dart not found in generated files"));
+
+        // form style with explode - the default - puts every entry on the wire under its own
+        // property name. Handing the whole map to _queryParams stringifies it with
+        // Map.toString(), which is what used to happen. A collection value repeats the key per
+        // non-null element ('multi').
+        TestUtils.assertFileContains(apiFile.toPath(),
+                "(filter as Map).forEach((entryKey, dynamic entryValue) => queryParams.addAll(_queryParams('multi', entryKey.toString(), entryValue is Iterable ? entryValue.where((e) => e != null).toList() : entryValue)));");
+        TestUtils.assertFileNotContains(apiFile.toPath(), "_queryParams('', 'filter', filter)");
+
+        // a declared map behaves the same way, and needs no cast
+        TestUtils.assertFileContains(apiFile.toPath(),
+                "typedFilter.forEach((entryKey, dynamic entryValue) => queryParams.addAll(_queryParams('multi', entryKey.toString(), entryValue is Iterable ? entryValue.where((e) => e != null).toList() : entryValue)));");
+
+        // deepObject and form without explode both keep a single parameter
+        TestUtils.assertFileContains(apiFile.toPath(),
+                "_queryParams('', 'deepFilter', deepFilter)",
+                "_queryParams('', 'flatFilter', flatFilter)");
+    }
+
     @Test(description = "Enum properties with defaults should emit enum constructor, not string literal")
     public void testEnumDefaultUsesEnumConstructor() throws Exception {
         List<File> files = generateDartNativeFromSpec(

samples/openapi3/client/petstore/dart2/petstore_client_lib_fake/lib/api/fake_api.dart

@@ -1382,7 +1382,8 @@ class FakeApi {
       queryParams.addAll(_queryParams('csv', 'url', url));
       queryParams.addAll(_queryParams('multi', 'context', context));
     if (language != null) {
-      queryParams.addAll(_queryParams('', 'language', language));
+      // form style, explode: one query parameter per entry, keyed by the property name; a collection repeats the key per non-null element
+      language.forEach((entryKey, dynamic entryValue) => queryParams.addAll(_queryParams('multi', entryKey.toString(), entryValue is Iterable ? entryValue.where((e) => e != null).toList() : entryValue)));
     }
       queryParams.addAll(_queryParams('', 'allowEmpty', allowEmpty));