finos / finos/symphony-bdk-java

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

Open
#886 1 comment 0 reactions 1 assignee Claimed by @thibauult View on GitHub
[type] cicd
Dominant language
Java
Stars
29
Forks
77
Avg merge
1d 23h
Merged PRs (30d)
3

Description

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

```bash
# 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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.