[Java] Add generateInsecureTlsHook option to omit the trust-all-certificates hook (jersey2/jersey3)

[K3vChan]

Fixes #24785

The jersey2 and jersey3 ApiClient templates unconditionally emit
disableCertificateValidation(), which builds an X509TrustManager with empty
checkClientTrusted/checkServerTrusted bodies and installs it into the
SSLContext. CodeQL reports this as java/insecure-trustmanager at high
severity, which fails the code scanning check on any PR that adds or touches the
generated client. Sonar's java:S4830 flags the same pattern.

The method is a protected opt-in hook — nothing in the generated client calls
it, and the javadoc on customizeClientBuilder tells you to override and invoke
it if you want it. But analysers flag code as written, not as reached, so
projects that commit their generated client (or scan target/) carry a
high-severity alert for a method they never use, with no way to opt out today:

• no configOption gates the block — it is unconditional template text;
• suppression comments do not survive regeneration;
• .openapi-generator-ignore excludes whole files, and ApiClient is the class
  you configure, so it cannot be skipped.

What this changes

Adds a generateInsecureTlsHook option that gates the method, the javadoc lines
that point at it, and the seven imports that become unused without it
(SSLContext, TrustManager, X509TrustManager, X509Certificate,
SecureRandom, KeyManagementException, NoSuchAlgorithmException).

It defaults to true, so generated output is unchanged. Anyone who
overrides customizeClientBuilder and calls the hook keeps compiling. Opting
out is explicit:

<configOptions>
  <generateInsecureTlsHook>false</generateInsecureTlsHook>
</configOptions>

Scope

Limited to jersey2 and jersey3. okhttp-gson contains a similar trust-all
X509TrustManager, but there it sits inside applySslSettings() behind the
runtime verifyingSsl field, which has a public setVerifyingSsl(boolean)
setter and is a documented feature. Gating that would be a breaking change, so
it is left alone. native, apache-httpclient and resttemplate do not emit
the block at all.

Testing

• Added testInsecureTlsHookGeneratedByDefault and
  testInsecureTlsHookOmittedWhenDisabled to JavaClientCodegenTest, both run
  against jersey2 and jersey3 via a data provider (4 cases). The second
  asserts the method, the X509TrustManager and each of the seven imports are
  absent.
• Full JavaClientCodegenTest: 278 tests, 0 failures.
• Regenerated every bin/configs/java*.yaml sample: no diff, confirming
  the default preserves current output.
• Generated jersey2 and jersey3 clients with the option off and confirmed no
  residue of the method or its imports, and that spacing around the removal
  stays correct (one blank line between the neighbouring members).
• Regenerated generator docs.

PR checklist

• Read the contribution guidelines.
• Ran the build and updated samples and docs:

  ./mvnw clean package
  ./bin/generate-samples.sh ./bin/configs/java*.yaml
  ./bin/utils/export_docs_generators.sh
  

  Samples produced no diff, as expected for a default-preserving change. Docs
  were regenerated and are included.
• Filed against master as a non-breaking change.
• @mentioning the technical committee for the affected libraries: @xhh
  (Java Jersey2), and @bbdouglas @wing328 as Java maintainers, in case you would
  prefer a different option name or a different default.

---

Summary by cubic

Adds a generateInsecureTlsHook option for jersey2/jersey3 so the generated ApiClient no longer has to include the trust-all disableCertificateValidation hook that static analyzers flag as java/insecure-trustmanager (fixes #24785).

The option defaults to true, so generated output is unchanged; docs previously advertised a false default because the CLI option wasn't explicitly registered with one, which is now fixed. Setting it to false removes the hook, its javadoc, and the seven imports that become unused. okhttp-gson is left untouched because its equivalent is a live runtime feature behind setVerifyingSsl, not a dead method.

New Features

• generateInsecureTlsHook is a new configOptions boolean for jersey2/jersey3, defaulting to true.
• Regenerating all existing Java samples produces no diff.

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

[cubic-dev-ai]

1 issue found across 6 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="docs/generators/java-microprofile.md">

<violation number="1" location="docs/generators/java-microprofile.md:59">
P2: This option is documented for java-microprofile but is a no-op there. java-microprofile (JavaMicroprofileServerCodegen) extends JavaClientCodegen, so the unconditionally-registered CliOption at JavaClientCodegen.java:287 propagates here and to every other Java generator, yet only the jersey2/jersey3 ApiClient mustache templates consult generateInsecureTlsHook. Users of this generator see an option that does nothing, contradicting the PR's stated jersey2/jersey3 scope. Add the CliOption (and its additionalProperties defaulting) only for the jersey2/jersey3 libraries, or otherwise filter it from generators whose templates never read it.</violation>
</file>

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: This option is documented for java-microprofile but is a no-op there. java-microprofile (JavaMicroprofileServerCodegen) extends JavaClientCodegen, so the unconditionally-registered CliOption at JavaClientCodegen.java:287 propagates here and to every other Java generator, yet only the jersey2/jersey3 ApiClient mustache templates consult generateInsecureTlsHook. Users of this generator see an option that does nothing, contradicting the PR's stated jersey2/jersey3 scope. Add the CliOption (and its additionalProperties defaulting) only for the jersey2/jersey3 libraries, or otherwise filter it from generators whose templates never read it.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/generators/java-microprofile.md, line 59:

<comment>This option is documented for java-microprofile but is a no-op there. java-microprofile (JavaMicroprofileServerCodegen) extends JavaClientCodegen, so the unconditionally-registered CliOption at JavaClientCodegen.java:287 propagates here and to every other Java generator, yet only the jersey2/jersey3 ApiClient mustache templates consult generateInsecureTlsHook. Users of this generator see an option that does nothing, contradicting the PR's stated jersey2/jersey3 scope. Add the CliOption (and its additionalProperties defaulting) only for the jersey2/jersey3 libraries, or otherwise filter it from generators whose templates never read it.</comment>

<file context>
@@ -56,6 +56,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |generateBuilders|Whether to generate builders for models| |false|
 |generateClientAsBean|For resttemplate, restclient and webclient, configure whether to create `ApiClient.java` and Apis clients as bean (with `@Component` annotation).| |false|
 |generateConstructorWithAllArgs|whether to generate a constructor for all arguments| |false|
+|generateInsecureTlsHook|Generate the ApiClient.disableCertificateValidation hook, which trusts all TLS certificates (default to true). Set to false to omit it, e.g. when static analysis flags the trust-all TrustManager it contains. Available on `jersey2`, `jersey3` libraries.| |false|
 |gradleProperties|Append additional Gradle properties to the gradle.properties file| |null|
 |groupId|groupId in generated pom.xml| |org.openapitools|
</file context>