[JAVA] Add generic okhttp client

RA
10d ago
+587628-47

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 an opt-in okhttp library to the Java client generator that produces OkHttp 5.4.0 clients for Gson, Jackson 2/3, and JSON-B. Existing okhttp-gson generation remains the default and byte-identical; the new library disables openApiNullable, and Jackson 3 clients require Java 17.

Client generation

  • Adds serializer-specific JSON handling, OAuth retry that reports token-endpoint failures, AWS4 signing, streaming, insecure-TLS hooks, composed models, builders, and JSpecify support.
  • Ports the latest okhttp-gson fixes: JSON header parameter content, JavaDoc default escaping, complex container defaults, case-insensitive and UUID inner enums, and raw @XmlEnumValue.
  • Fixes request compression and progress reporting, response cleanup, date handling, header normalization, read-only deserialization, validation, JSON-B discriminator and additionalProperties handling (including parents without a discriminator), and Gson null-safe composed adapters.
  • Gson and JSON-B now reject enum values excluded via not: enum — including on inherited properties — so complementary oneOf branches resolve to exactly one.
  • Initializes the shared serializer eagerly, detects byte[] responses for all serializers, returns raw bodies for String results in JSON-B, and fixes base64 byte serialization.
  • Preserves additionalProperties through toBuilder().build(), stops enabling reflection-based model equality in the new okhttp samples, and drops unused Jackson imports.
  • Rejects the misleading defaultToEmptyContainer=true spelling, supports grouped parameters, dynamic operations, oneOf/anyOf, and Jackson 3 JsonTypeName imports, and depends on okhttp-jvm in the POM and sbt builds.

Samples and validation

  • Adds 27 sample configurations across all four serializers, including Jackson 3, JSON-B, OpenAPI 3.1, AWS4, streaming, parcelable models, and user-defined templates.
  • Wires the samples into Maven profiles and CI on the appropriate JDK versions, including Java 17 for Jackson 3.
  • Existing okhttp-gson users need no migration; generate the new client with --library okhttp.