Spike: diff openapi-generator 6.6.0 vs 7.x generated output before the 4.x migration

[thibauult]

Context

Ahead of the BDK 4.x major (Spring Boot 4 + Java 25 baseline), the OpenAPI generator has to move from 6.6.0 to 7.x. Version 6.6.0 is a 2023 release and cannot be expected to run on JDK 25 or on current Gradle.

That bump is not a routine dependency update, because the generated sources are part of the published API surface. Consumers construct these models, read their getters, and catch their exceptions:

• 377 generated classes under com.symphony.bdk.gen.api and com.symphony.bdk.gen.api.model
• generated from 5 remote specs (Agent, Pod, Auth, Login, Users) pinned to a finos/symphony-api-spec commit
• library = 'jersey2', invokerPackage = 'com.symphony.bdk.http.api', supportingFiles: "false" — so the invoker layer (ApiClient, ApiResponse, Pair, TypeReference) is hand-written in symphony-bdk-http-api and only the API/model classes are generated
• three custom Mustache templates in templates/ (api.mustache, pojo.mustache, modelInnerEnum.mustache)

A generator major bump routinely changes nullable wrapping, fluent-setter shape, equals/hashCode/toString, enum representation, annotation sets, and required-vs-optional constructor parameters. Any of those is a consumer-visible breaking change.

The failure mode we want to avoid is not a build error. It is a consumer upgrading to 4.0.0, finding that a model class they construct no longer compiles, and finding no mention of it in the migration guide.

Ask

Generate the API and model sources with both 6.6.0 and 7.x into two separate trees, diff them in full, and produce a written summary of every consumer-visible difference.

Roughly:

# baseline
./gradlew :symphony-bdk-core:compileJava
cp -r symphony-bdk-core/build/generated/openapi /tmp/gen-6.6.0

# candidate: bump the plugin in buildSrc/build.gradle, then
./gradlew clean :symphony-bdk-core:compileJava
cp -r symphony-bdk-core/build/generated/openapi /tmp/gen-7.x

diff -r /tmp/gen-6.6.0 /tmp/gen-7.x

Two things worth specific attention:

1. The custom templates. pojo.mustache carries the project's Jakarta patch. If 7.x restructured the upstream template, a naive rebase can silently drop it — and since useJakartaEe may now be a first-class configOption, the correct fix may be to delete the customization rather than port it. Each of the three templates should be re-justified against 7.x upstream rather than merely made to apply.
2. configOptions. dateLibrary: "java8" and sortParamsByRequiredFlag: "false" are set today. Confirm both still exist and still mean the same thing in 7.x — a changed default would show up as a broad signature change across all 377 classes.

Also worth checking while in here: whether 7.x's jersey3 library targets the Jersey version Spring Boot 4 pins, and whether org.openapitools:jackson-databind-nullable:0.2.6 (currently constrained in symphony-bdk-bom) still has a role under 7.x's nullable strategy.

Acceptance criteria

• Both generator versions run to completion and the two output trees are captured
• Full diff -r reviewed, not sampled
• A written summary of consumer-visible changes, with before/after signatures for anything a consumer constructs or reads directly — suitable for dropping into the 4.x migration guide
• Each of the three custom templates is either rebased with a stated reason or deleted with a stated reason
• Confirmation that the regenerated sources contain no javax.* imports
• Any change nobody can explain is flagged rather than accepted

Relevant files

• buildSrc/build.gradle — openapi-generator-gradle-plugin version
• buildSrc/src/main/groovy/bdk.java-codegen-conventions.gradle — shared generator config
• symphony-bdk-core/build.gradle — the 5-API apisToGenerate loop and its generator config
• templates/ — the three custom Mustache templates

Why now

This is cheap to do (two generator runs) and expensive to discover late. Knowing the size of the generated diff up front determines whether the generator bump can ride along with the rest of the 4.x work or needs to be scheduled and communicated as a breaking change in its own right.

[thibauult]

Spike results

Generated all 5 specs with openapi-generator-gradle-plugin 6.6.0 (current) and 7.14.0 (latest 7.x), captured both build/generated/openapi trees, and diffed in full after normalizing import order and the @Generated timestamp/version comment (cosmetic only, not consumer-visible). Verified determinism by rebuilding each version twice from a clean state.

Bottom line

The bump is safe once one required template fix lands. Without it, there's a broad silent regression.

The regression: pojo.mustache uses a variable upstream repurposed

Upstream renamed the Mustache variable used to build list/map fluent-builder method names. In 6.6.0, nameInCamelCase rendered PascalCase; in 7.x its meaning changed to real camelCase, and upstream introduced nameInPascalCase for the old behavior, migrating all their own templates to it (confirmed in AbstractJavaCodegen/upstream pojo.mustache diff between the two tags). Our forked templates/pojo.mustache (lines 124 and 149) still uses the old variable, so under 7.14.0 as-is it silently renders:

// 6.6.0 (and upstream 7.x)                      // 7.x with our un-rebased template
public AdminStreamAttributes addMembersItem(…)    public AdminStreamAttributes addmembersItem(…)
public V3Health putServicesItem(…)                public V3Health putservicesItem(…)

This hits 98 of 292 model classes / ~135 methods — every generated model with a List<> or Map<> property. It compiles fine (nothing catches it), and any consumer code calling .addXxxItem(...) / .putXxxItem(...) would simply fail to compile after upgrading, with nothing in a diff or changelog pointing at why.

Fix (validated): in templates/pojo.mustache, change:

add{{nameInCamelCase}}Item(...)   →   add{{nameInPascalCase}}Item(...)
put{{nameInCamelCase}}Item(...)   →   put{{nameInPascalCase}}Item(...)

After applying this and rebuilding, the two generated trees are byte-identical except for the two items below.

Remaining differences (both benign)

1. 15 orphaned *AllOf model classes disappear (MessageAllOf, V2MessageAllOf, SignalAllOf, RoomCreatedMessageAllOf, RoomDeactivatedMessageAllOf, RoomMemberDemotedFromOwnerMessageAllOf, RoomMemberPromotedToOwnerMessageAllOf, RoomReactivatedMessageAllOf, RoomUpdatedMessageAllOf, UserJoinedRoomMessageAllOf, UserLeftRoomMessageAllOf, V2PresenceAllOf, V2RoomSearchCriteriaAllOf, V2UserPresenceAllOf, ConnectionRequestMessageAllOf) — a change in how the generator flattens single-allOf-with-inline-properties schemas. Verified: none of these classes are referenced anywhere in the generated tree or in hand-written BDK code — they were always dead, unreachable artifacts of allOf composition. Technically a removal of public classes (breaking only if a consumer imported one directly, which there's no legitimate reason to do). Worth one line in the migration guide, negligible risk.

2. Error.java's javadoc header flips between the Agent spec's and the Login spec's info.title/description/version text — no field/method changes, comment only. Root cause is pre-existing, unrelated build fragility: Error is defined independently in multiple specs, skipOverwrite = true means whichever generateX task runs first "wins" the shared file, and today only two such conflicts (AuthRequest, SystemApi) are pinned via explicit dependsOn ordering in symphony-bdk-core/build.gradle. Error isn't pinned. The generator bump doesn't cause this directly, but changes Gradle's task scheduling enough to flip which spec wins the race — confirmed stable within each version across repeated clean rebuilds, different across versions. Suggest a small follow-up: add explicit ordering for the Error model too (or accept as cosmetic).

Template verdicts

• pojo.mustache — REBASE (the 2-line fix above). The Jakarta-related part of the customization — hardcoded @javax.annotation.Nullable with the @Nonnull branch dropped, instead of upstream's @{{javaxPackage}}.annotation.Nullable — should be kept, not deleted. Traced upstream's applyJakartaPackage(): setting useJakartaEe=true blindly rewrites the javaxPackage variable to "jakarta" everywhere it's used, including this line. But javax.annotation.Nullable/Nonnull come from JSR-305 (com.google.code.findbugs:jsr305), which was never migrated to Jakarta EE — there's no jakarta.annotation.Nullable class to reference. Upstream's own template still has this latent bug in 7.14.0. Our hardcode is correct today and becomes actively load-bearing (not just currently redundant) the moment useJakartaEe is ever turned on for a jersey3 move.
• api.mustache — KEEP as-is. It's a wholesale rewrite around our own ApiClient/TypeReference/Pair invoker, not a small patch on top of upstream. Every variable it depends on (allParams, queryParams, returnType, httpMethod, etc.) is unchanged between 6.6.0 and 7.14.0 — confirmed by zero differences in all 31 generated *Api.java files.
• modelInnerEnum.mustache — KEEP as-is. Also a full independent rewrite (Jackson-only, no gson/JSON-B/XML support, custom fromValue() that logs+returns null on an unknown value instead of throwing). Upstream's 7.x additions (isUri enum support, vendorExtensions.x-implements) aren't exercised by any of our 5 specs — confirmed zero diffs in every enum-bearing model.

configOptions and other checks from the issue

• dateLibrary: "java8" and sortParamsByRequiredFlag: "false" — both option keys and semantics are unchanged in 7.14.0 (confirmed in generator source, and empirically since all 31 API classes are byte-identical).
• jersey3 vs. Spring Boot 4's Jersey pin — turns out to be a non-issue for us either way: our custom api.mustache never emits JAX-RS types directly (it drops the upstream GenericType import entirely), so the jersey2 library choice in openapi-generator only affects code-generation style, not the actual runtime Jersey version. That's entirely controlled by symphony-bdk-bom's own jersey-bom coordinate (currently 3.1.12) and the hand-written symphony-bdk-http-jersey2 module, both already jakarta-namespaced. jersey2 is not deprecated in 7.14.0, so there's no forced migration here.
• org.openapitools:jackson-databind-nullable:0.2.6 — has no role at all, in either generator version. JsonNullable never appears in any generated file because all 5 specs are Swagger 2.0 and never set nullable: true. This is dead weight in symphony-bdk-bom today, unaffected by the bump — candidate for removal in an unrelated cleanup.
• javax.* imports — zero import javax.* statements in either version's generated output. javax.annotation.Generated and javax.annotation.Nullable appear via fully-qualified inline references (not imports) in every model, which is correct and expected — JSR-250/JSR-305 stay in the javax.annotation namespace permanently regardless of Jakarta EE migration status.

Suggested next step

Bump buildSrc/build.gradle to 7.14.0 together with the pojo.mustache 2-line fix in the same change (the fix must ride along with the bump — nameInPascalCase doesn't exist in 6.6.0's data model). Optionally fold in the Error task-ordering fix. With that, the generator major bump has zero consumer-visible impact beyond the 15 dead-class removals, which is a one-line mention in the 4.x migration guide.