[JAVA] Add generic okhttp client

[rar91279]

Adds a new okhttp library to the Java client generator, marked [BETA]. It is derived from
okhttp-gson, but decoupled from Gson: a single template set emits working clients for Gson
(default), Jackson 2, Jackson 3 and JSON-B, on OkHttp 5.4.0, and it honours the existing
useJspecify option.

okhttp-gson is untouched and remains the default library — its generated output is byte-identical
to master. This is purely additive for existing users; the new library is opt-in via
--library okhttp.

openapi-generator generate -g java --library okhttp \
  -p serializationLibrary=jackson -p useJackson3=true -p useJspecify=true

JavaClientCodegen

• Registers the library, adds it to JSPECIFY_SUPPORTED_LIBRARIES and to the useJackson3
  allowlist, and reuses the okhttp-gson supporting-file branch without forcing a serialization
  library.
• Resolves isGson/isJackson/isJsonb after the serialization switch, where
  getSerializationLibrary() is authoritative. No new early property reads, so no behavioural risk
  to other libraries.
• Forces openApiNullable off for JSON-B: jackson-databind-nullable is Jackson-only and the pom
  omits it there, so leaving the flag on emitted JsonNullable references that could not resolve.
• Applies the x-enum-as-string discriminator rewrite for every serialization library, not just
  Jackson. This is not a Jackson nicety — a child schema that narrows an inherited discriminator to
  a single-value enum otherwise generates a getter that cannot override the parent's String
  getter. JsonNullable/JsonIgnore imports stay Jackson-only.
• Extends useSingleRequestParameter and the oneOf/anyOf ModelNull handling to the new
  library; both were gated on allowlists that excluded it, even though its templates support them.

Samples — 27 configs covering the four serialization variants, JSpecify for each of Jackson 2/3
and JSON-B, oneOf/anyOf, nullable-required, AWS4 signing, dynamic operations, grouped
parameters, parcelable models, streaming, Swagger 1/2 annotations, OpenAPI 3.1, the echo API and
user-defined templates.

One rename — bin/configs/java-okhttp-user-defined-templates.yaml →
java-okhttp-gson-user-defined-templates.yaml. It generated the okhttp-gson sample despite the
neutral name, and every other okhttp-gson config is already named java-okhttp-gson-*. Content
unchanged, generated sample untouched.

PR checklist

• Read the contribution guidelines.
• Run the following to build the project and update samples:

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

  (For Windows users, please run the script in WSL)
  Commit all changed files.
  This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master.
  These must match the expectations made by your contribution.
  You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*.
  IMPORTANT: Do NOT purge/delete any folders/files (e.g. tests) when regenerating the samples as manually written tests may be removed.
• If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

@bbdouglas @sreeshas @jfiala @lukoyanov @cbornet @jeff9finger @karismann @Zomzog @lwlee2608 @martin-mfg @KannaKim

---

Summary by cubic

Adds a new okhttp Java client library that generates OkHttp 5.4.0 clients for Gson (default), Jackson 2/3, and JSON‑B. okhttp-gson remains the default and byte‑identical; the new library is opt‑in via --library okhttp. Also standardizes discriminator handling and fixes correctness issues in the new templates.

• Codegen: registers okhttp in JavaClientCodegen, resolves serializer flags after serializationLibrary, adds okhttp to JSPECIFY_SUPPORTED_LIBRARIES, extends useSingleRequestParameter and oneOf/anyOf null handling, forces openApiNullable=false for JSON‑B, and applies the x-enum-as-string discriminator rewrite across all serializers.
• Templates: new Java/libraries/okhttp/* with per‑client JSON config, payload bytes passed to auth, and AWS4 signed last; RetryingOAuth uses OkHttp (drops Apache Oltu). Correctness fixes include gzip content length restoration, progress body/source memoization, signing x‑amz-* headers, Jackson 2 RFC3339 date module registration, and @JsonbTransient for additionalProperties.
• Samples/CI/docs: adds 27 okhttp sample configs (Gson/Jackson 2/3/JSON‑B, JSpecify, oneOf/anyOf, streaming, AWS4, OpenAPI 3.1, grouped params, dynamic operations, parcelable), wires them into GitHub Actions and new Maven profiles, and updates generator docs. User‑defined template configs include a rename for the okhttp-gson sample and new okhttp/okhttp-jackson variants.

Usage and migration

• Generate with: openapi-generator generate -g java --library okhttp -p serializationLibrary=gson|jackson|jsonb [-p useJackson3=true] [-p useJspecify=true].
• No migration for existing okhttp-gson users.
• JSON‑B: openApiNullable is disabled; jackson-databind-nullable types are not generated.

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

[cubic-dev-ai]

10 issues found across 3000 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="samples/client/others/java/okhttp-jackson-oneOf/settings.gradle">

<violation number="1" location="samples/client/others/java/okhttp-jackson-oneOf/settings.gradle:1">
P3: The new settings.gradle is missing a trailing newline at end of file, unlike every other sample settings.gradle in this directory. Add a final newline to match conventions and avoid a spurious diff marker.</violation>
</file>

<file name="samples/client/others/java/okhttp-jackson-oneOf/src/main/java/org/openapitools/client/RFC3339InstantDeserializer.java">

<violation number="1" location="samples/client/others/java/okhttp-jackson-oneOf/src/main/java/org/openapitools/client/RFC3339InstantDeserializer.java:32">
P2: This deserializer is never installed in the generated mapper, so the `_fromString` override that normalizes space-separated RFC3339 values never runs. Register `RFC3339JavaTimeModule` in `JSON` alongside `JavaTimeModule`, or omit this supporting class.</violation>
</file>

<file name="samples/client/others/java/okhttp-jsonb-oneOf/src/main/java/org/openapitools/client/ApiResponse.java">

<violation number="1" location="samples/client/others/java/okhttp-jsonb-oneOf/src/main/java/org/openapitools/client/ApiResponse.java:23">
P3: Fields declare `final private` where the conventional order is `private final`. This is non-idiomatic modifier ordering throughout this new file.</violation>

<violation number="2" location="samples/client/others/java/okhttp-jsonb-oneOf/src/main/java/org/openapitools/client/ApiResponse.java:42">
P3: The javadoc for the `data` parameter says "deserialized from response bod" — a typo for "body". Worth fixing while this file is new.</violation>
</file>

<file name="samples/client/echo_api/java/okhttp-user-defined-templates/src/main/java/org/openapitools/client/auth/HttpBearerAuth.java">

<violation number="1" location="samples/client/echo_api/java/okhttp-user-defined-templates/src/main/java/org/openapitools/client/auth/HttpBearerAuth.java:40">
P2: When callers read the bearer token before configuring one, `getBearerToken()` throws a `NullPointerException` even though `applyToParams()` treats an unset token as valid unauthenticated state. Return null when `tokenSupplier` is unset, matching the other auth getters.</violation>
</file>

<file name="samples/client/echo_api/java/okhttp-user-defined-templates/src/main/java/org/openapitools/client/Configuration.java">

<violation number="1" location="samples/client/echo_api/java/okhttp-user-defined-templates/src/main/java/org/openapitools/client/Configuration.java:39">
P2: During concurrent first access, `AtomicReference.updateAndGet` may retry this updater after a CAS failure, so `apiClientFactory.get()` can construct and discard extra clients. Initialize the singleton under a non-retryable critical section, or keep factory invocation outside a retryable updater.</violation>
</file>

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

<violation number="1" location="modules/openapi-generator/src/main/resources/Java/libraries/okhttp/additional_properties.mustache:39">
P1: When `serializationLibrary=jsonb` is used with `additionalProperties: true`, JSON-B cannot round-trip undeclared fields. Unknown response keys are ignored, while values added through `putAdditionalProperty` are not emitted under their original names; add a JSON-B serializer/deserializer that captures and flattens undeclared fields and excludes the backing bean property.</violation>
</file>

<file name="samples/client/echo_api/java/okhttp-jackson-user-defined-templates/modelCopy/TestQueryStyleDeepObjectExplodeTrueObjectAllOfQueryObjectParameter.java">

<violation number="1" location="samples/client/echo_api/java/okhttp-jackson-user-defined-templates/modelCopy/TestQueryStyleDeepObjectExplodeTrueObjectAllOfQueryObjectParameter.java:23">
P2: The `@JsonTypeName` is emitted as `"java"` instead of the model name, because `{{name}}` in pojo.mustache resolves to the language name when the model is rendered through this `files`/modelCopy configuration. This corrupts the Jackson discriminator value that serialization depends on; the same models in `src/main/java/.../model/` emit the correct names. Fix the variable used in the modelCopy generation (e.g. render the model's name/discriminator value) so it matches the src output.</violation>
</file>

<file name="samples/client/others/java/okhttp-jackson-oneOf/git_push.sh">

<violation number="1" location="samples/client/others/java/okhttp-jackson-oneOf/git_push.sh:47">
P2: When the directory already has a non-`origin` remote, this check skips adding `origin`, but the script later pulls and pushes from `origin`. Check specifically for `origin` before deciding whether to add it.</violation>

<violation number="2" location="samples/client/others/java/okhttp-jackson-oneOf/git_push.sh:54">
P1: When `GIT_TOKEN` is set, this command stores the credential in plaintext in `.git/config` and exposes it through Git remote inspection. Use Git's credential helper or `GIT_ASKPASS` instead of embedding the token in the remote URL.</violation>
</file>

<sub>Note: This PR contains a large number of files. cubic only reviews up to 400 files per PR, so some files may not have been reviewed. cubic prioritizes the most important files to review.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: When serializationLibrary=jsonb is used with additionalProperties: true, JSON-B cannot round-trip undeclared fields. Unknown response keys are ignored, while values added through putAdditionalProperty are not emitted under their original names; add a JSON-B serializer/deserializer that captures and flattens undeclared fields and excludes the backing bean property.

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/resources/Java/libraries/okhttp/additional_properties.mustache, line 39:

<comment>When `serializationLibrary=jsonb` is used with `additionalProperties: true`, JSON-B cannot round-trip undeclared fields. Unknown response keys are ignored, while values added through `putAdditionalProperty` are not emitted under their original names; add a JSON-B serializer/deserializer that captures and flattens undeclared fields and excludes the backing bean property.</comment>

<file context>
@@ -0,0 +1,55 @@
+  {{#isJackson}}
+  @JsonAnyGetter
+  {{/isJackson}}
+  public Map<String, Object> getAdditionalProperties() {
+    return additionalProperties;
+  }
</file context>

[cubic-dev-ai]

P1: When GIT_TOKEN is set, this command stores the credential in plaintext in .git/config and exposes it through Git remote inspection. Use Git's credential helper or GIT_ASKPASS instead of embedding the token in the remote URL.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/others/java/okhttp-jackson-oneOf/git_push.sh, line 54:

<comment>When `GIT_TOKEN` is set, this command stores the credential in plaintext in `.git/config` and exposes it through Git remote inspection. Use Git's credential helper or `GIT_ASKPASS` instead of embedding the token in the remote URL.</comment>

<file context>
@@ -0,0 +1,63 @@
+        echo "[INFO] \$GIT_TOKEN (environment variable) is not set. Using the git credential in your environment."
+        git remote add origin https://${git_host}/${git_user_id}/${git_repo_id}.git
+    else
+        git remote add origin https://${git_user_id}:"${GIT_TOKEN}"@${git_host}/${git_user_id}/${git_repo_id}.git
+    fi
+
</file context>

[cubic-dev-ai]

P2: When callers read the bearer token before configuring one, getBearerToken() throws a NullPointerException even though applyToParams() treats an unset token as valid unauthenticated state. Return null when tokenSupplier is unset, matching the other auth getters.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/echo_api/java/okhttp-user-defined-templates/src/main/java/org/openapitools/client/auth/HttpBearerAuth.java, line 40:

<comment>When callers read the bearer token before configuring one, `getBearerToken()` throws a `NullPointerException` even though `applyToParams()` treats an unset token as valid unauthenticated state. Return null when `tokenSupplier` is unset, matching the other auth getters.</comment>

<file context>
@@ -0,0 +1,74 @@
+   * @return The bearer token
+   */
+  public String getBearerToken() {
+    return tokenSupplier.get();
+  }
+
</file context>

Suggested change

	return tokenSupplier.get();
	return Optional.ofNullable(tokenSupplier).map(Supplier::get).orElse(null);

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

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="samples/client/others/java/okhttp-jackson-oneOf/git_push.sh">

<violation number="1" location="samples/client/others/java/okhttp-jackson-oneOf/git_push.sh:32">
P2: `git_branch` is never defined in this script (it only sets git_user_id, git_repo_id, release_note, git_host), so `-b "$git_branch"` expands to an empty string and `git init -b ""` fails with `fatal: invalid initial branch name: ''` (exit 128). The generating template modules/openapi-generator/src/main/resources/_common/git_push.sh.mustache still uses plain `git init` and defines no git_branch, so this sample is also inconsistent with its source. Either drop `-b "$git_branch"` (matching the template) or set git_branch to a default like `master` before calling git init.</violation>
</file>

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: git_branch is never defined in this script (it only sets git_user_id, git_repo_id, release_note, git_host), so -b "$git_branch" expands to an empty string and git init -b "" fails with fatal: invalid initial branch name: '' (exit 128). The generating template modules/openapi-generator/src/main/resources/_common/git_push.sh.mustache still uses plain git init and defines no git_branch, so this sample is also inconsistent with its source. Either drop -b "$git_branch" (matching the template) or set git_branch to a default like master before calling git init.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/others/java/okhttp-jackson-oneOf/git_push.sh, line 32:

<comment>`git_branch` is never defined in this script (it only sets git_user_id, git_repo_id, release_note, git_host), so `-b "$git_branch"` expands to an empty string and `git init -b ""` fails with `fatal: invalid initial branch name: ''` (exit 128). The generating template modules/openapi-generator/src/main/resources/_common/git_push.sh.mustache still uses plain `git init` and defines no git_branch, so this sample is also inconsistent with its source. Either drop `-b "$git_branch"` (matching the template) or set git_branch to a default like `master` before calling git init.</comment>

<file context>
@@ -29,7 +29,7 @@ if [ -z "${release_note}" ]; then
 
 # Initialize the local directory as a Git repository
-git init
+git init -b "$git_branch"
 
 # Adds the files in the local repository and stages them for commit.
</file context>

Suggested change

	git init -b "$git_branch"
	git init