Redocly / Redocly/redoc

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

Open
#461 4 comments 10 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

help wanted Type: Enhancement
Dominant language
TypeScript
Stars
25.9k
Forks
2.4k
Avg merge
13h 10m
Merged PRs (30d)
4

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

The issue names ReDoc's OpenAPI documentation rendering but no source file or test. Start by locating where schema enum values are rendered, then verify that x-extensible-enum and compatible x-*-enum extensions appear in the generated documentation without changing closed enum behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, typescript
Domain
api, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.