Generate code for OpenAPI 3.2 query/additionalOperations/in:querystring

[khayashi4337]

Status: Draft — blocked on swagger-parser releasing OAS 3.2 support

This PR is not ready to merge. It builds on #24969 (already open, please
review that one first — it warns instead of silently dropping unrecognized
path-item operations like 3.2's query), and depends on parsing support
that only exists in a fork of swagger-parser
(swagger-api/swagger-parser#2402, itself a draft blocked on a swagger-core
fork). pom.xml currently points at a locally-installed swagger-parser
SNAPSHOT that isn't available to anyone else — this PR cannot build or pass
CI (the RequireReleaseDeps enforcer rule rejects it outright) until that
chain lands upstream.

I opened it as a draft anyway so the codegen work is visible and reviewable
in context. I'll drop the dependency on the forks and rebase once
swagger-core/swagger-parser cut releases with OAS 3.2 support.

What this adds (on top of #24969)

Generates code for the OAS 3.2 constructs that the swagger-parser fork now
parses into the model: the query HTTP method, additionalOperations
(arbitrary-named path-item operations), and in: querystring parameters.

Scope: the cross-language core path (so query/additionalOperations
are picked up structurally everywhere), plus nine generator/library
combinations wired up end-to-end and verified on the wire:

Generator	Library
java	okhttp-gson (default)
go	—
python	urllib3
typescript-fetch	fetch
rust	reqwest
ruby	httpx
php	guzzle
csharp	generichost
kotlin	jvm-okhttp4

Generators that have not opted in warn and skip 3.2 operations instead of
emitting non-compiling references to HTTP-method enum constants that don't
exist for their target language.

• additionalOperations keys are sent as wire HTTP method names verbatim
  (a new wireHttpMethod path bypasses the existing uppercase-normalization
  that's correct for the 8 fixed methods but wrong for arbitrary ones)
• in: querystring becomes CodegenParameter.isQueryStringParam, typed as
  a plain string via the target language's own type mapping (content-derived
  model import/setContent is skipped for it)
• Each language gates supportsAdditionalOperations() /
  supportsQueryStringParameters() per-library with a concrete reason —
  e.g. Python: aiohttp/httpx call method.upper() and would corrupt
  customMethod into CUSTOMMETHOD; Ruby: typhoeus crashes on
  non-alphanumeric tokens and faraday rejects them; C#: restsharp's Method
  enum rejects non-standard tokens; Kotlin: only jvm-okhttp4's shadow
  request config can carry custom methods.
• A supportsAdditionalOperations() hook (default false, mirroring the
  existing supportsQueryStringParameters() hook) makes generators that
  haven't opted in warn-and-skip rather than silently emit references to
  HTTP-method enum constants (PURGE, QUERY, ...) that don't exist for
  their target language — this was a real gap caught during review: the
  shared pipeline originally let these values reach every language's
  templates, and 15+ non-Java templates (Spring, Kotlin, TypeScript, ...)
  would have produced non-compiling output for a 3.2 spec with no warning at
  all.

Additional fixes in this branch (kept as separate commits)

• allOf form required flags (bc20a2c12d3, 7ab9da53d49): required
  flags for form parameters are now collected only from the schema's own
  required plus its allOf chain, matched by baseName — oneOf/anyOf
  branch properties no longer leak into required, fixing a regression where
  properties+oneOf models made every form field required.
• Generated-code identifier collisions (Kotlin, PHP): spec parameters
  named like template locals (localVariable*), API members
  (request, basePath, parseDateToQueryString), or implicit receivers
  (it, value) no longer shadow generated code — names are renamed or
  qualified while wire names stay unchanged. Includes a wire-level Vert.x
  fix where collected form parameters were never actually sent.
• $ in wire names (Kotlin): wire names containing $ (e.g. OData
  $filter) are escaped in generated Kotlin string literals across all
  client libraries, matching jvm-okhttp's existing behavior.

Known limitations (disclosed, not blocking this draft)

• Only the nine generator/library combinations above emit 3.2 operations;
  every other library (including the other Kotlin libraries, Java's
  non-okhttp-gson libraries, and the non-fetch TypeScript generators)
  warns and skips.
• At least one generator (k6) builds its supporting script from its own
  independent traversal of the model rather than going through the shared,
  now-gated pipeline, so it isn't covered by the new
  supportsAdditionalOperations() guard. A handful of other generators use
  a similar direct-traversal pattern and haven't been individually audited.
  None of this is new — it follows from swagger-core's PathItem.HttpMethod
  enum gaining a QUERY value, which any code iterating that enum directly
  will now see, independent of anything in this PR.
• MergedSpecBuilder (multi-spec merge) now includes additionalOperations
  in its merge and operation-ID conflict detection.
• OpenApiEvaluator still assumes the fixed HttpMethod enum and doesn't
  support arbitrary additionalOperations.

Testing

Core classes: DefaultGeneratorTest (27), DefaultCodegenTest (174+7),
JavaClientCodegenTest (287), InlineModelResolverTest (62),
OpenAPINormalizerTest (71) — 628 total, 0 failures.

Per-language verification goes beyond unit tests — generated clients were
compiled and exercised against raw socket captures to prove the wire
behavior (verbatim method casing, verbatim query-string appending, form
bodies actually transmitted):

• Kotlin package: 579 tests, 0 failures; kotlinc compile checks for
  okhttp4/vertx/ktor/multiplatform/spring generated clients, plus a live
  ServerSocket capture asserting form fields reach the wire.
• C# (generichost): dotnet restore+run with a raw TcpListener capture of
  QUERY/custom-method requests on both net8.0 and net10.0.
• PHP (guzzle), Ruby (httpx), Rust (reqwest), Go, Python (urllib3),
  typescript-fetch: raw TCP/socket captures of the actual HTTP request
  lines and bodies.

Sample regeneration (./bin/generate-samples.sh, 124+ configs) confirmed
clean — diffs limited to the intended template changes.

---

🤖 Generated with Claude Code

---

Summary by cubic

Generates code for OpenAPI 3.2's query HTTP method, additionalOperations map, and in: querystring parameters, wired end-to-end for Java (okhttp-gson), Go, Python (urllib3), typescript-fetch, Rust (reqwest), Ruby (httpx), PHP (guzzle), C# (generichost), and Kotlin (jvm-okhttp4). Also fixes issue #24212: with --skip-validate-spec, unrecognized path-item operations are flagged with an explicit warning naming the dropped member instead of being silently dropped.

Behavior changes

• additionalOperations keys are sent verbatim as the wire HTTP method name; invalid RFC 9110 tokens, and case-variants some clients would normalize, are warned about and skipped.
• in: querystring parameters become CodegenParameter.isQueryStringParam and append their value verbatim to the request path, skipping content-derived model imports. Operations using them are now skipped with a warning in generators without support, instead of being sent through ordinary name=value serialization that corrupted the already-encoded value.
• A new supportsAdditionalOperations() hook (default false) makes unsupported generators warn-and-skip instead of emitting references to HTTP-method enum constants that don't exist for their target language. Unsupported generators no longer flatten inline schemas from callbacks attached to 3.2 operations.
• When the parser produces no OpenAPI object, generation fails immediately with the parser's diagnostics instead of a generic downstream error.

Additional fixes

• k6 now skips 3.2 query operations with a warning instead of emitting http.query() calls (which throw at runtime), and no longer leaves empty request groups when a query-only path coexists with a sibling dataextract operation.
• Parameters and properties colliding with generated template locals or API members are renamed (wire names preserved) across Kotlin and PHP so generated clients compile and send the intended values. Kotlin also escapes $ in paths and wire names across all libraries (retrofit2 applies it only to string literals, not identifiers), jvm-vertx multipart file params transmit file content instead of the local path with array values as separate parts, and jvm-ktor binds its form builder explicitly so a field named it no longer shadows it.
• Form-parameter required flags now match the schema property name, so allOf-inherited required fields are no longer dropped and oneOf/anyOf branches no longer force fields required.
• The dropped-operation warning for issue [BUG] Unrecognized path-item operations (e.g. OpenAPI 3.2 'query') are silently dropped from generated code with --skip-validate-spec #24212 no longer false-positives on quoted segments nested inside path names or on dotted custom method names; verbatim query handling was also hardened across Go (raw query ordering), Python (case-exact method dispatch), and typescript-fetch (no longer treats a '?' inside a URL fragment as an existing query, and warns on fetch-forbidden verbs). Rust escapes markdown specials in generated method-name docs.
• The FILTER normalizer evaluates additionalOperations entries independently, so a key like GET alongside the fixed get: field can no longer overwrite the fixed method's entry.

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

[cubic-dev-ai]

8 issues found across 98 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="modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/JavaClientCodegen.java">

<violation number="1" location="modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/JavaClientCodegen.java:1435">
P1: This enables 3.2 webhook operations, but dynamic webhook methods cannot resolve them because the okhttp-gson lookup map contains paths only. With `dynamicOperations=true`, those webhook calls throw `ApiException("Operation not found in OAS")`; register webhook operations in the lookup map or guard this support for dynamic webhook generation.</violation>
</file>

<file name="modules/openapi-generator/src/test/java/org/openapitools/codegen/DefaultGeneratorTest.java">

<violation number="1" location="modules/openapi-generator/src/test/java/org/openapitools/codegen/DefaultGeneratorTest.java:483">
P3: These assertions depend on the iteration order of `PathItem.getAdditionalOperations()`, which is a plain `Map` — its insertion order is not guaranteed by the swagger-core fork, and `DefaultGenerator` iterates it with `forEach` in that order. If the map is a `HashMap`, the `get(1)`/`get(2)` assertions for "PURGE" vs "customMethod" rest on hash-ordered iteration. Make the assertions order-independent, e.g., look up each operation by `operationId` and assert its `httpMethod`.</violation>
</file>

<file name="pom.xml">

<violation number="1" location="pom.xml:1290">
P1: This pins the core build to an unavailable fork snapshot, so clean CI and consumer builds fail during dependency resolution before generation tests run. Keep the released parser version until the required upstream artifact is published, or declare the repository/artifact source that supplies this snapshot.</violation>
</file>

<file name="modules/openapi-generator/src/main/java/org/openapitools/codegen/config/MergedSpecBuilder.java">

<violation number="1" location="modules/openapi-generator/src/main/java/org/openapitools/codegen/config/MergedSpecBuilder.java:747">
P1: `existing.addAdditionalOperation` merges custom operations without the source spec's root-level security. Extend `propagateRootSecurityToOperations` to cover `additionalOperations` before merging, or these generated methods lose their authentication requirements.</violation>
</file>

<file name="modules/openapi-generator/src/main/resources/Java/libraries/okhttp-gson/ApiClient.mustache">

<violation number="1" location="modules/openapi-generator/src/main/resources/Java/libraries/okhttp-gson/ApiClient.mustache:1918">
P1: Dynamic clients generated for 3.2 specs will not compile because this branch calls parser methods absent from the generated client's pinned `swagger-parser-v3:2.0.30`. Update the generated build dependencies to a parser release containing the OpenAPI 3.2 `PathItem` methods before emitting these calls.</violation>
</file>

<file name="modules/openapi-generator/src/test/resources/3_2/rust-invalid-method.yaml">

<violation number="1" location="modules/openapi-generator/src/test/resources/3_2/rust-invalid-method.yaml:13">
P3: This fixture also documents a promised WARN ("skipped with a warning"), but the only test consuming it (RustClientCodegenTest.testReqwestSkipsInvalidMethodNames) asserts just that the operation is dropped, so the skip could silently lose its warning without failing. Capture the logger output and assert the "not a valid RFC 9110 token" warning is emitted for the "MY METHOD" operation.</violation>
</file>

<file name="modules/openapi-generator/src/test/java/org/openapitools/codegen/java/JavaClientCodegenTest.java">

<violation number="1" location="modules/openapi-generator/src/test/java/org/openapitools/codegen/java/JavaClientCodegenTest.java:5281">
P3: These new generation tests only assert substrings and never compile the output, unlike every other generation test in this file (e.g., the MicroProfile test above calls validateJavaSourceFiles(files)). The PR's core risk is generated-code validity for a brand-new parameter kind (in: querystring) and verbatim HTTP method names; a regression that produces non-compiling DefaultApi.java/ApiClient.java would pass these tests. The non-dynamic test (no pathItem.getQuery()/getAdditionalOperations() references) and the negative dynamic test can compile against the pinned parser, so capture `List<File> files = ...generate();` and call validateJavaSourceFiles(files). Skipping validation is only unavoidable for the positive dynamic test, whose output intentionally references parser methods the pinned release lacks.</violation>
</file>

<file name="modules/openapi-generator/src/test/java/org/openapitools/codegen/rust/RustClientCodegenTest.java">

<violation number="1" location="modules/openapi-generator/src/test/java/org/openapitools/codegen/rust/RustClientCodegenTest.java:492">
P2: This end-to-end test runs a full `cargo build` + `cargo run` with network dependency resolution in the default unit-test suite whenever cargo is on PATH and index.crates.io:443 is reachable. On any dev machine or CI image where those hold, every `mvn test` of this module now spends minutes compiling and can flake on crates.io/network hiccups. Gate it behind an opt-in system property (e.g. `-Drust.e2e=true`) and skip otherwise, so the default suite stays fast and offline-deterministic.</violation>
</file>

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: This enables 3.2 webhook operations, but dynamic webhook methods cannot resolve them because the okhttp-gson lookup map contains paths only. With dynamicOperations=true, those webhook calls throw ApiException("Operation not found in OAS"); register webhook operations in the lookup map or guard this support for dynamic webhook generation.

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/java/org/openapitools/codegen/languages/JavaClientCodegen.java, line 1435:

<comment>This enables 3.2 webhook operations, but dynamic webhook methods cannot resolve them because the okhttp-gson lookup map contains paths only. With `dynamicOperations=true`, those webhook calls throw `ApiException("Operation not found in OAS")`; register webhook operations in the lookup map or guard this support for dynamic webhook generation.</comment>

<file context>
@@ -1426,4 +1427,31 @@ protected void applyJspecify() {
+    protected boolean supportsQueryStringParameters() {
+        // only the okhttp-gson api.mustache serializes an `in: querystring`
+        // parameter as the whole (already-encoded) query string
+        return isLibrary(OKHTTP_GSON) || StringUtils.isBlank(getLibrary());
+    }
+
</file context>

[cubic-dev-ai]

P1: This pins the core build to an unavailable fork snapshot, so clean CI and consumer builds fail during dependency resolution before generation tests run. Keep the released parser version until the required upstream artifact is published, or declare the repository/artifact source that supplies this snapshot.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At pom.xml, line 1290:

<comment>This pins the core build to an unavailable fork snapshot, so clean CI and consumer builds fail during dependency resolution before generation tests run. Keep the released parser version until the required upstream artifact is published, or declare the repository/artifact source that supplies this snapshot.</comment>

<file context>
@@ -1287,7 +1287,7 @@
         <spotbugs-plugin.version>3.1.12.2</spotbugs-plugin.version>
         <swagger-parser-groupid.version>io.swagger.parser.v3</swagger-parser-groupid.version>
-        <swagger-parser.version>2.1.47</swagger-parser.version>
+        <swagger-parser.version>2.1.49-SNAPSHOT</swagger-parser.version>
         <testng.version>7.10.2</testng.version>
         <violations-maven-plugin.version>1.34</violations-maven-plugin.version>
</file context>

Suggested change

	<swagger-parser.version>2.1.49-SNAPSHOT</swagger-parser.version>
	<swagger-parser.version>2.1.47</swagger-parser.version>

[khayashi4337]

Thanks for the review, @cubic-dev-ai.

This is correct, and stems from the same cause as the finding on ApiClient.mustache/build.gradle.mustache/build.sbt.mustache below: the OpenAPI 3.2 model support this PR depends on (PathItem.query, PathItem.additionalOperations, etc.) doesn't exist in any released swagger-core/swagger-parser version yet -- only in a local snapshot build.

This PR is intentionally a Draft for that reason, tracking an in-progress upstream chain:

• swagger-core#5253 / [REQ][JAVA]: Add option to generate arrays with "uniqueItems" true as Sets rather than Lists #5254 / [Java][WebClient] Removal of Encoding in the Query-Params in order to prevent double encoding #5255 (other contributors, open) -- QUERY method + SpecVersion enum groundwork
• swagger-core#5326 (mine, draft) -- OAS 3.2 model support, blocked on the above
• swagger-parser#2401 (mine, open) / [BUG] Cannot generate server with invokePackage=Websupport\\InvoiceValidation #2402 (mine, draft) -- parses/validates the new fields, blocked on swagger-core#5326

Once those land upstream I'll drop the snapshot pin and rebase. Flagging this explicitly so it isn't mistaken for an oversight.

[cubic-dev-ai]

P1: existing.addAdditionalOperation merges custom operations without the source spec's root-level security. Extend propagateRootSecurityToOperations to cover additionalOperations before merging, or these generated methods lose their authentication requirements.

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/java/org/openapitools/codegen/config/MergedSpecBuilder.java, line 747:

<comment>`existing.addAdditionalOperation` merges custom operations without the source spec's root-level security. Extend `propagateRootSecurityToOperations` to cover `additionalOperations` before merging, or these generated methods lose their authentication requirements.</comment>

<file context>
@@ -722,6 +727,27 @@ private void mergePathItem(PathItem existing, PathItem incoming, String pathKey)
+                    // WARN: keep the first (existing) operation, skip the incoming one.
+                    return;
+                }
+                existing.addAdditionalOperation(method, operation);
+            });
+        }
</file context>

[cubic-dev-ai]

P3: These assertions depend on the iteration order of PathItem.getAdditionalOperations(), which is a plain Map — its insertion order is not guaranteed by the swagger-core fork, and DefaultGenerator iterates it with forEach in that order. If the map is a HashMap, the get(1)/get(2) assertions for "PURGE" vs "customMethod" rest on hash-ordered iteration. Make the assertions order-independent, e.g., look up each operation by operationId and assert its httpMethod.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At modules/openapi-generator/src/test/java/org/openapitools/codegen/DefaultGeneratorTest.java, line 483:

<comment>These assertions depend on the iteration order of `PathItem.getAdditionalOperations()`, which is a plain `Map` — its insertion order is not guaranteed by the swagger-core fork, and `DefaultGenerator` iterates it with `forEach` in that order. If the map is a `HashMap`, the `get(1)`/`get(2)` assertions for "PURGE" vs "customMethod" rest on hash-ordered iteration. Make the assertions order-independent, e.g., look up each operation by `operationId` and assert its `httpMethod`.</comment>

<file context>
@@ -448,6 +448,102 @@ public void testProcessPaths() throws Exception {
+        Assert.assertEquals(defaultList.size(), 3);
+        Assert.assertEquals(defaultList.get(0).operationId, "queryPets");
+        Assert.assertEquals(defaultList.get(0).httpMethod, "QUERY");
+        Assert.assertEquals(defaultList.get(1).operationId, "purgePets");
+        Assert.assertEquals(defaultList.get(1).httpMethod, "PURGE");
+        // additionalOperations keys are HTTP method names and must be sent verbatim
</file context>

[cubic-dev-ai]

P3: This fixture also documents a promised WARN ("skipped with a warning"), but the only test consuming it (RustClientCodegenTest.testReqwestSkipsInvalidMethodNames) asserts just that the operation is dropped, so the skip could silently lose its warning without failing. Capture the logger output and assert the "not a valid RFC 9110 token" warning is emitted for the "MY METHOD" operation.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At modules/openapi-generator/src/test/resources/3_2/rust-invalid-method.yaml, line 13:

<comment>This fixture also documents a promised WARN ("skipped with a warning"), but the only test consuming it (RustClientCodegenTest.testReqwestSkipsInvalidMethodNames) asserts just that the operation is dropped, so the skip could silently lose its warning without failing. Capture the logger output and assert the "not a valid RFC 9110 token" warning is emitted for the "MY METHOD" operation.</comment>

<file context>
@@ -0,0 +1,18 @@
+        '200':
+          description: ok
+    additionalOperations:
+      # contains a space - not a valid RFC 9110 token; must be skipped with a warning
+      "MY METHOD":
+        operationId: badMethod
</file context>

[cubic-dev-ai]

P3: These new generation tests only assert substrings and never compile the output, unlike every other generation test in this file (e.g., the MicroProfile test above calls validateJavaSourceFiles(files)). The PR's core risk is generated-code validity for a brand-new parameter kind (in: querystring) and verbatim HTTP method names; a regression that produces non-compiling DefaultApi.java/ApiClient.java would pass these tests. The non-dynamic test (no pathItem.getQuery()/getAdditionalOperations() references) and the negative dynamic test can compile against the pinned parser, so capture List<File> files = ...generate(); and call validateJavaSourceFiles(files). Skipping validation is only unavoidable for the positive dynamic test, whose output intentionally references parser methods the pinned release lacks.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At modules/openapi-generator/src/test/java/org/openapitools/codegen/java/JavaClientCodegenTest.java, line 5281:

<comment>These new generation tests only assert substrings and never compile the output, unlike every other generation test in this file (e.g., the MicroProfile test above calls validateJavaSourceFiles(files)). The PR's core risk is generated-code validity for a brand-new parameter kind (in: querystring) and verbatim HTTP method names; a regression that produces non-compiling DefaultApi.java/ApiClient.java would pass these tests. The non-dynamic test (no pathItem.getQuery()/getAdditionalOperations() references) and the negative dynamic test can compile against the pinned parser, so capture `List<File> files = ...generate();` and call validateJavaSourceFiles(files). Skipping validation is only unavoidable for the positive dynamic test, whose output intentionally references parser methods the pinned release lacks.</comment>

<file context>
@@ -5259,6 +5259,69 @@ public void testInsecureTlsHookOmittedWhenDisabled(String library) {
+                .contains("purgePetsCall(")
+                .contains("\"QUERY\"")
+                .contains("\"PURGE\"")
+                .contains("localVarPath = localVarPath + (localVarPath.contains(\"?\") ? \"&\" : \"?\") + qs;");
+    }
+
</file context>