Skip to content

[Core] Support map/object format for x-enum-varnames and x-enum-descriptions#23540

Open
emaarco wants to merge 1 commit intoOpenAPITools:masterfrom
emaarco:emaarco/x-enum-desc-map-fix
Open

[Core] Support map/object format for x-enum-varnames and x-enum-descriptions#23540
emaarco wants to merge 1 commit intoOpenAPITools:masterfrom
emaarco:emaarco/x-enum-desc-map-fix

Conversation

@emaarco
Copy link
Copy Markdown

@emaarco emaarco commented Apr 14, 2026

Summary

When x-enum-descriptions or x-enum-varnames are provided as a JSON object (map) instead of an array, the generator crashes with a Exception because it unconditionally casts the extension value to List<String>.

This PR adds support for both formats:

  • Array (existing, positional): ["desc1", "desc2"]
  • Map/Object (new, keyed by enum value): {"ENUM_VALUE": "description", ...}

Motivation

I encountered this when generating a Kotlin client from a real-world API (Markant public-api) that uses the map format for x-enum-descriptions:

"x-enum-descriptions": {
    "FRUITS_AND_VEGETABLES": "Fruits and vegetables assortment",
    "DRY": "Dry goods assortment",
    "FROZEN": "Frozen goods assortment"
}

The map format is also used in the ecosystem and supported by other tools. Since x-enum-descriptions is a vendor extension (not part of the official OpenAPI spec), there is no single canonical format — both array and object are valid conventions:

  • Redocly documents x-enumDescriptions exclusively as a map/object format: Redocly x-enumDescriptions docs
  • Speakeasy supports both formats for their equivalent extensions and recommends the map format as it's order-independent and resilient to additions: Speakeasy enum docs
  • openapi-generator currently only documents the array format: templating.md - enum

The map format has practical advantages over the array format:

  • Order-independent — descriptions stay correct even if enum values are reordered
  • Supports partial descriptions — not every enum value needs a description
  • No length-mismatch errors

Changes

  • DefaultCodegen.java: Modified updateEnumVarsWithExtensions to check instanceof List vs instanceof Map. For map format, keys are matched to enum values via toEnumValue(key, dataType) to ensure correct matching regardless of language-specific value transformations.
  • AbstractPhpCodegen.java: Same fix applied to the PHP codegen's override of the method.
  • DefaultCodegenTest.java: Added postProcessModelsEnumWithMapExtension test mirroring the existing array-based test.

Test plan

  • Existing postProcessModelsEnumWithExtension test still passes (array format — no regression)
  • New postProcessModelsEnumWithMapExtension test passes (map format)
  • Both x-enum-varnames and x-enum-descriptions work with map format

…iptions

The generator crashes with a ClassCastException when these vendor extensions
are provided as a JSON object (map) instead of an array. Both formats are
valid conventions used in the ecosystem (Redocly, Speakeasy, etc.).

For map format, keys are matched to enum values via toEnumValue(key, dataType)
to ensure correct matching regardless of language-specific value transformations.
Copy link
Copy Markdown
Contributor

@cubic-dev-ai cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No issues found across 3 files

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant