Escape parameter defaults in Java API Javadocs

[Felix-ming]

Fixes #24852.

Problem

The Java okhttp-gson generator renders parameter default values directly in @param Javadocs. Values containing Java block-comment delimiters can terminate or start a comment in the generated source and make the client fail to compile. This is observable downstream in apache/airflow#72466.

Solution

• Preserve the runtime default value unchanged.
• Add a Java-specific vendor extension containing a comment-safe value for Javadocs.
• Use the escaped value only for defaults rendered by the okhttp-gson API template.
• Add a regression fixture and test that validates the generated Java source.

Tests

• ./mvnw -pl modules/openapi-generator -am --batch-mode --no-transfer-progress -Dtest=JavaClientCodegenTest#shouldEscapeParameterDefaultsInOkHttpGsonApiJavadocs -Dsurefire.failIfNoSpecifiedTests=false test
• ./mvnw -pl modules/openapi-generator -am --batch-mode --no-transfer-progress -Dtest=JavaClientCodegenTest -Dsurefire.failIfNoSpecifiedTests=false test

Both commands pass; the full JavaClientCodegenTest class passes 290 tests.

[cubic-dev-ai]

1 issue found across 4 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:1151">
P2: The shared `JavaClientCodegen.postProcessParameter` now attaches the escaped `x-java-default-value-for-javadoc` extension to every parameter of every Java generator, but only the okhttp-gson api.mustache consumes it. The same compile-breaking Javadoc bug this PR fixes still exists in the other Java library templates that render `{{#defaultValue}}` raw inside `@param` comments (apache-httpclient line 49, feign lines 33/63/100, jersey2 lines 63/100, native lines 325/355/400/423, and equivalents in resttemplate/webclient, etc.). Since the extension is already available to all of them, swapping the one section token in each is a mechanical follow-up; otherwise a user on any other Java library hits the identical failure from apache/airflow#72466.</violation>
</file>

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The shared JavaClientCodegen.postProcessParameter now attaches the escaped x-java-default-value-for-javadoc extension to every parameter of every Java generator, but only the okhttp-gson api.mustache consumes it. The same compile-breaking Javadoc bug this PR fixes still exists in the other Java library templates that render {{#defaultValue}} raw inside @param comments (apache-httpclient line 49, feign lines 33/63/100, jersey2 lines 63/100, native lines 325/355/400/423, and equivalents in resttemplate/webclient, etc.). Since the extension is already available to all of them, swapping the one section token in each is a mechanical follow-up; otherwise a user on any other Java library hits the identical failure from apache/airflow#72466.

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 1151:

<comment>The shared `JavaClientCodegen.postProcessParameter` now attaches the escaped `x-java-default-value-for-javadoc` extension to every parameter of every Java generator, but only the okhttp-gson api.mustache consumes it. The same compile-breaking Javadoc bug this PR fixes still exists in the other Java library templates that render `{{#defaultValue}}` raw inside `@param` comments (apache-httpclient line 49, feign lines 33/63/100, jersey2 lines 63/100, native lines 325/355/400/423, and equivalents in resttemplate/webclient, etc.). Since the extension is already available to all of them, swapping the one section token in each is a mechanical follow-up; otherwise a user on any other Java library hits the identical failure from apache/airflow#72466.</comment>

<file context>
@@ -1138,6 +1139,19 @@ private static boolean isMultipartType(List<Map<String, String>> consumes) {
+            // default is rendered inside a JavaDoc comment, where Java block-comment delimiters
+            // would otherwise terminate or start a comment block in generated source.
+            parameter.vendorExtensions.put(
+                    JAVA_DEFAULT_VALUE_FOR_JAVADOC, escapeUnsafeCharacters(parameter.defaultValue));
+        }
+    }
</file context>