Redocly/redoc

Support x-extensible-enum (and other x-enum if possible)

Open

#461 opened on Apr 19, 2018

View on GitHub
 (4 comments) (10 reactions) (0 assignees)TypeScript (21,877 stars) (2,272 forks)batch import
Type: Enhancementhelp wanted

Description

Didn't see this already listed, so apologies if its duplicated.

In our product, we've decided against using closed enum lists, because of the breaking changes that can happen at the downstream client level if lists ever grow. The problem with this is that it means we need to go to a vendor extension, which we've done so, but no downstream clients (like ReDoc) can surface these in the documentation.

My proposal would be to simply treat x--enum the same as enum, such that ReDoc surfaces the values correctly. This will cover x-extensible-enum, as well as other implementations that have gone down the same path (such as ours, which is modeled after x--enum)

The inspiration for this request came from Zalando's approach. Zalando came up with nice framework within their API guidelines to handle this, which would be incredibly useful to upstream into the specification itself. I submitted a request to OpenAPI to evaluate this, but lets say this will take a looooong time to propagate down to the community

https://zalando.github.io/restful-api-guidelines/#112

Should: Used Open-Ended List of Values (x-extensible-enum) Instead of Enumerations [112] Enumerations are per definition closed sets of values, that are assumed to be complete and not intended for extension. This closed principle of enumerations imposes compatibility issues when an enumeration must be extended. To avoid these issues, we strongly recommend to use an open-ended list of values instead of an enumeration unless:

the API has full control of the enumeration values, i.e. the list of values does not depend on any external tool or interface, and

the list of value is complete with respect to any thinkable and unthinkable future feature.

To specify an open-ended list of values use the marker x-extensible-enum as follows:

deliver_methods:
  type: string
  x-extensible-enum:
    - parcel
    - letter
    - email

Contributor guide