Swagger Codegen vs. OpenAPI Generator: Consistent polymorphic model generation in CI/CD
0 reputation · 02 Jun 2024, 18:36 UTC
0 reputation · 02 Jun 2024, 18:36 UTC
When a team uses a repeatable CI/CD pipeline to generate SDKs from an OpenAPI 3.x spec, the mapping of oneOf and anyOf schemas to statically‑typed language models is a frequent source of drift. The OpenAPI Generator fork of Swagger Codegen supports a wide array of target languages, but each language’s template implements its own heuristic for polymorphism (sealed interfaces, union types, generic Object, etc.). Because these heuristics live in Mustache templates, a minor generator release can alter the generated class hierarchy without any visible change to the command‑line flags, leaving teams unable to pin a stable output. Moreover, the discriminator.mapping feature is honored inconsistently across languages, further complicating cross‑language parity.
Given this uncertainty, teams need a clear path to enforce a consistent polymorphic model strategy across Java, TypeScript, and Go while keeping the spec as the single source of truth. What approaches can be adopted to lock in a stable oneOf/anyOf mapping in a CI/CD pipeline? Which generator versions or template forks provide the most reliable behavior for this feature? Is there a forthcoming CLI option to select a polymorphism strategy explicitly?
34275 reputation · 03 Jun 2024, 04:51 UTC
There is no single CLI flag that forces one consistent polymorphism strategy across Java, TypeScript, and Go. The only reliable way to lock output is to treat the generator and its templates as pinned build dependencies, enforce strict discriminator definitions in the spec, and fail CI when generated code drifts from a committed baseline.
Confirmed: Swagger Codegen is legacy; OpenAPI Generator is the active fork. Polymorphic mapping for oneOf and anyOf is implemented independently in each language's Mustache templates. There is no universal cross-language strategy option in stable releases, and a minor template change can alter class hierarchies without any change to command-line flags.
Likely but version-dependent: Java generators tend to expose discriminator-lookup options; TypeScript generators tend toward union types with optional discriminator fields; Go generators often emit generic structures because native sum types are limited. These behaviors vary by release and library, so verify them against your pinned version rather than assuming parity.
oneOf/anyOf parent should declare discriminator.propertyName and an explicit mapping for each child. Missing mappings cause fallback to Object or any in several languages.git diff --exit-code generated/.# Illustrative CI snippet (adapt to your toolchain)
docker run --rm -v "${PWD}:/local" \
openapitools/openapi-generator-cli:<exact-tag> generate \
-i /local/openapi.yaml \
-g <language> \
-t /local/templates/<language> \
-o /local/generated/<language>
git add generated/
git diff --cached --exit-code || exit 1
No specific OpenAPI Generator version is universally "most reliable" for polymorphism across all three languages; reliability comes from the pinning discipline above. Prefer the latest stable release you have already validated over the newest available. Template forks should be adopted only after reviewing diffs against upstream, because vendoring increases maintenance cost and delays upstream fixes.
There is no forthcoming CLI option to select a polymorphism strategy explicitly in stable releases today. Any such feature would be speculative until it is released and documented; treat it as unverified.
One detail would change the recommendation: whether your specs already define explicit discriminator.propertyName and mapping for every subschema. If they do not, closing that spec gap matters more than any generator or template change.
Use comments to ask for clarification. Post a solution as an answer.
No question comments on this page.