You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
[BUG][Java] Nested <OperationId>Request class collides with request body model, breaking existing methods #25646
With useSingleRequestParameter set to true or static, the Java client generates a nested class named <OperationId>Request inside each *Api class. When a request body model has that same name, the nested class shadows the model inside the *Api class:
The existing positional method's body parameter now resolves to the nested class, so existing callers that pass the model no longer compile.
The nested class's body field is typed as the nested class itself, so there is no way to send the real body.
Enabling the option is expected to be additive (the positional methods are still generated), but in this case it breaks the existing API.
openapi-generator version
Seen with 7.14.0 and 7.27.0 (Gradle plugin). On master, Java/libraries/webclient/single_request_parameter.mustache uses the same <OperationId>Request naming with no collision handling.
OpenAPI declaration file content or url
Minimal spec showing the shape (an operation updateFoo whose request body model is UpdateFooRequest). The behaviour was observed on a larger spec with the same pattern; this reduced version has not been run separately.
generatorName: java, library: webclient, useSingleRequestParameter: static (same result with true).
Steps to reproduce
Generate a Java webclient client from the spec above with useSingleRequestParameter set to static or true.
Look at the generated *Api class.
Actual: a nested public static class UpdateFooRequest containing private UpdateFooRequest updateFooRequest. The positional updateFoo(String id, UpdateFooRequest updateFooRequest) now resolves to the nested class, so code passing the model UpdateFooRequest fails with incompatible types: <model>.UpdateFooRequest cannot be converted to <Api>.UpdateFooRequest.
Expected: no shadowing, for example by giving the request class a non-colliding name (such as UpdateFooRequestParams) or by using fully qualified model names in signatures when a collision exists.
Related issues/PRs
#19827 (adds the option to WebClient), #20679, #24568. I did not find an existing issue for this collision.
changed the title [-][BUG] Description[/-][+][BUG][Java] Nested <OperationId>Request class collides with request body model, breaking existing methods[/+]on Nov 12, 2026
Reproduce with the spec above (java / webclient, useSingleRequestParameter = true and static).
In the Java codegen, detect when the generated <OperationId>Request name collides with a model name, and only in that case give the nested class a non-colliding name (e.g. UpdateFooRequestParams, as suggested above). Non-colliding operations keep today's naming, so existing users see no change.
Check whether other Java libraries that support useSingleRequestParameter share the same naming and apply the same handling there.
Add a unit test with a colliding spec, and regenerate the samples.
If maintainers would rather keep the nested class name and fully qualify the model type in signatures instead, I'm happy to go that way. Let me know before I open the PR.
Thanks, good point. Name mappings do work as a workaround: either --model-name-mappings UpdateFooRequest=... or --operation-id-name-mappings updateFoo=... avoids the clash. But both rename part of the public API (the model class or the method), so turning on useSingleRequestParameter still breaks existing callers, which is what the option is meant to avoid. They're also per-operation manual fixes.
It's also not just a corner case: inline request bodies are auto-named <operationId>_request, which becomes <OperationId>Request in Java, exactly the nested class name. So any operation with an inline request body collides by default.
I've opened #25652, which renames the nested class only when it would actually shadow an imported model (to <OperationId>RequestParams). Non-colliding output is unchanged; the existing samples regenerate identically. Happy to change the approach if you'd prefer something else.
Rather than trying to calculate a best-fit for what a naming pattern could be (or incrementing it with numbers until it fits), would not a suitable pattern be to expose the mapping/suffix entirely to the consumer and let them opt-in to a different suffix if the default one defined in the generator is not suitable?
For the inline request body there already is a hatch with the https://github.com/OpenAPITools/openapi-generator/blob/master/docs/customization.md#inline-schema-naming, but one might want to have something similar for singleRequestParameter? I would assume that other generators might have similar cases where some construct is forged internally by the generator, and that one would really want to have a more open-ended config that allows the user to specify anything? The though there being that one does not want to drown in this-setting-suffix-config and that-setting-suffix-config but rather that there is some more generic suffix-setting=this-suffix=MySuffix,that-suffix=MyOtherSuffix and that valid indata can be derived from reading configs available to the used language.
Thanks @Mattias-Sehlstedt, agreed that auto-incrementing (...RequestParams2) is hard to predict, and an explicit option fits better with the existing mapping options @wing328 mentioned.
Proposal:
Add a Java client option singleRequestParameterSuffix (default Request), so the nested class is <OperationId><suffix>. The default output stays the same, and only the request wrapper's name changes when a user opts in. Unlike modelNameMappings / operationIdNameMappings, it doesn't rename the model or the method.
Drop the numeric fallback.
One open question: as noted above, every operation with an inline request body collides by default (<operationId>_request becomes <OperationId>Request). With only the option, those users still get uncompilable code until they find the setting. Two ways to handle that:
a) detect the collision and log a warning pointing to singleRequestParameterSuffix (output unchanged, user opts in), or
b) detect the collision and apply a single fixed fallback (<OperationId>RequestParams, no numbering), while still letting the option override it.
I lean towards (a) for predictability, but I'm happy to go with whichever you prefer.
A generic --suffix-settings key=value,... for all generator-internal names sounds useful too, but it touches many generators, so I'd track it as a separate issue and keep this PR scoped to the Java webclient/restclient libraries.
I've updated #25652 to option (a): new singleRequestParameterSuffix option (default Request, so existing output is unchanged), no automatic renaming, and a warning that points to the option when the class name collides with a model. Happy to adjust if you'd prefer a different approach.
Activity
[-][BUG] Description[/-][+][BUG][Java] Nested <OperationId>Request class collides with request body model, breaking existing methods[/+]rajeshvasa commentedon Nov 13, 2026
I'd like to work on this.
Plan:
<OperationId>Requestname collides with a model name, and only in that case give the nested class a non-colliding name (e.g.UpdateFooRequestParams, as suggested above). Non-colliding operations keep today's naming, so existing users see no change.If maintainers would rather keep the nested class name and fully qualify the model type in signatures instead, I'm happy to go that way. Let me know before I open the PR.
wing328 commentedon Nov 13, 2026
would https://github.com/OpenAPITools/openapi-generator/blob/master/docs/customization.md#name-mapping help?
one can use these options to rename property/parameter/method names to avoid name collision
rajeshvasa commentedon Nov 13, 2026
Thanks, good point. Name mappings do work as a workaround: either
--model-name-mappings UpdateFooRequest=...or--operation-id-name-mappings updateFoo=...avoids the clash. But both rename part of the public API (the model class or the method), so turning on useSingleRequestParameter still breaks existing callers, which is what the option is meant to avoid. They're also per-operation manual fixes.It's also not just a corner case: inline request bodies are auto-named
<operationId>_request, which becomes<OperationId>Requestin Java, exactly the nested class name. So any operation with an inline request body collides by default.I've opened #25652, which renames the nested class only when it would actually shadow an imported model (to
<OperationId>RequestParams). Non-colliding output is unchanged; the existing samples regenerate identically. Happy to change the approach if you'd prefer something else.Mattias-Sehlstedt commentedon Nov 13, 2026
Rather than trying to calculate a best-fit for what a naming pattern could be (or incrementing it with numbers until it fits), would not a suitable pattern be to expose the mapping/suffix entirely to the consumer and let them opt-in to a different suffix if the default one defined in the generator is not suitable?
For the inline request body there already is a hatch with the https://github.com/OpenAPITools/openapi-generator/blob/master/docs/customization.md#inline-schema-naming, but one might want to have something similar for singleRequestParameter? I would assume that other generators might have similar cases where some construct is forged internally by the generator, and that one would really want to have a more open-ended config that allows the user to specify anything? The though there being that one does not want to drown in
this-setting-suffix-configandthat-setting-suffix-configbut rather that there is some more genericsuffix-setting=this-suffix=MySuffix,that-suffix=MyOtherSuffixand that valid indata can be derived from reading configs available to the used language.rajeshvasa commentedon Nov 13, 2026
Thanks @Mattias-Sehlstedt, agreed that auto-incrementing (
...RequestParams2) is hard to predict, and an explicit option fits better with the existing mapping options @wing328 mentioned.Proposal:
singleRequestParameterSuffix(defaultRequest), so the nested class is<OperationId><suffix>. The default output stays the same, and only the request wrapper's name changes when a user opts in. UnlikemodelNameMappings/operationIdNameMappings, it doesn't rename the model or the method.One open question: as noted above, every operation with an inline request body collides by default (
<operationId>_requestbecomes<OperationId>Request). With only the option, those users still get uncompilable code until they find the setting. Two ways to handle that:a) detect the collision and log a warning pointing to
singleRequestParameterSuffix(output unchanged, user opts in), orb) detect the collision and apply a single fixed fallback (
<OperationId>RequestParams, no numbering), while still letting the option override it.I lean towards (a) for predictability, but I'm happy to go with whichever you prefer.
A generic
--suffix-settings key=value,...for all generator-internal names sounds useful too, but it touches many generators, so I'd track it as a separate issue and keep this PR scoped to the Java webclient/restclient libraries.Replace automatic rename with singleRequestParameterSuffix option (Op…
rajeshvasa commentedon Nov 14, 2026
I've updated #25652 to option (a): new
singleRequestParameterSuffixoption (defaultRequest, so existing output is unchanged), no automatic renaming, and a warning that points to the option when the class name collides with a model. Happy to adjust if you'd prefer a different approach.