Zudoku
Supported Extensions

x-enum-descriptions

Use x-enum-descriptions to explain what each value of an enum means. Zudoku lists the descriptions next to their values wherever the enum is shown: in request and response schemas, object properties, and parameters. Without it, readers see the values only.

Zudoku accepts both x-enum-descriptions and x-enumDescriptions. If a schema sets both, the camelCase x-enumDescriptions takes precedence.

Location

The extension is added at the Schema Object level, next to the enum it describes. For an array, add it to the items schema. For a parameter, add it to the parameter's schema.

OptionTypeDescription
x-enum-descriptions or x-enumDescriptionsobject or string[]A description for each enum value, in one of the formats below.

Formats

Map of values to descriptions

Use an object whose keys are enum values and whose values are descriptions.

YAMLCode
status: type: string enum: [CREATED, IN_TRANSIT, DELIVERED, EXCEPTION] x-enum-descriptions: CREATED: Manifest logged and cargo sealed in the stasis bay, awaiting launch clearance. IN_TRANSIT: Cargo is aboard a freighter, currently in warp between waypoints. DELIVERED: Docked at the destination port and signed for by the recipient. EXCEPTION: Delayed by an anomaly such as an ion storm, customs hold or quantum drift.

Map nested under values

Some generators wrap the same map in a values property. Zudoku reads it the same way.

YAMLCode
status: type: string enum: [CREATED, IN_TRANSIT, DELIVERED, EXCEPTION] x-enum-descriptions: values: CREATED: Manifest logged and cargo sealed in the stasis bay. IN_TRANSIT: Cargo is aboard a freighter, currently in warp. DELIVERED: Docked at the destination port and signed for. EXCEPTION: Delayed by an anomaly such as an ion storm.

Array aligned with enum

Use an array of strings where each entry describes the enum value at the same position. Tools such as openapi-generator emit this format.

YAMLCode
status: type: string enum: [CREATED, IN_TRANSIT, DELIVERED, EXCEPTION] x-enum-descriptions: - Manifest logged and cargo sealed in the stasis bay. - Cargo is aboard a freighter, currently in warp. - Docked at the destination port and signed for. - Delayed by an anomaly such as an ion storm.

Keep the array in the same order as enum. Zudoku pairs entries by position, ignores empty entries, and ignores entries beyond the length of enum.

Behavior

  • A value without a description is still listed in the enum, with an empty description.
  • Entries that aren't strings are ignored.
  • If no usable descriptions remain, Zudoku shows the plain list of enum values.
Last modified on