swagger-api / swagger-api/swagger-ui
Support enums with descriptions as per OpenAPI v3.1
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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