swagger-api / swagger-api/swagger-ui

Support enums with descriptions as per OpenAPI v3.1

Open
#10,104 0 comments 5 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

Content & configuration

Swagger/OpenAPI definition:

cvv_check:
 type: string
 title: CVV check
 description: When processed, result from checking the CVV/CVC value on the transaction.
 oneOf:
   - const: D
     description: Suspicious transaction
   - const: I
     description: Failed data validation check
   - const: M
     description: Match
   - const: N
     description: No Match
   - const: P
     description: Not Processed
   - const: S
     description: Should have been present
   - const: U
     description: Issuer unable to process request
   - const: X
     description: Card does not support verification
Is your feature request related to a problem?

Previous versions of OpenAPI didn't allow declaring enums with custom titles and descriptions, making it hard to describe formats that use integer as underlying enum representation.

Starting with OpenAPI v3.1, which has oneOf and other combinatorial operators, the officially recommended approach is to use YAML like above that combines oneOf + list of consts into essentially an enum with named items.

SwaggerUI can show this schema as expected, but the "Try it out" editor still shows such fields as simple text inputs with no validation.

Describe the solution you'd like

Such fields should be rendered as dropdowns that show list of human-readable names (title), shows description on hover, and actually translates to the underlying const as the value passed in the form.

Basically, it should behave in the same way as enum does, except for mapping values to their human-readable names.

Describe alternatives you've considered
Additional context

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

Start at the Try it out editor's existing enum handling and OpenAPI v3.1 schema support; no file or test is named in the issue. Use the provided cvv_check schema to verify a dropdown, title and description display, and submission of the underlying const value.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, openapi
Domain
api, frontend
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.