OpenAPI extension: x-enumDescriptions
The enum (short for "enumeration") fields in OpenAPI allow you to restrict the value of a field to a list of allowed values. These values need to be short and machine-readable, but that can make them harder for humans to parse and work with.
Add x-enumDescriptions to your OpenAPI description to show a helpful table of enum options and an explanation of what each one means. This field supports Markdown.
Include all options
When x-enumDescriptions is used, only the options listed in this section are displayed in documentation. Check that all options are included to ensure the documentation is complete.
Options
| Option | Type | Description |
|---|---|---|
| x-enumDescriptions | [ Enum description object ] | An array of the enum values and descriptions to include in the documentation. |
Enum description object
| Option | Type | Description |
|---|---|---|
| enum value | string | More information or explanation about when to choose this value. |
Examples
The following example shows a schema with two short-named options, and the x-enumDescriptions entry to list all enum entries and give additional context for each:
components: schemas: TicketType: description: Type of ticket being purchased. Use `general` for regular museum entry and `event` for tickets to special events. type: string enum: - event - general x-enumDescriptions: event: Event Tickets _(timed entry)_ general: General Admission example: event
Resources
- See all theme.openapi configuration settings.
- Control which extensions are included in your API reference documentation with the showExtensions configuration setting.
- See a full list of supported OpenAPI extensions.