swagger-api / swagger-api/swagger-ui
Rendering enum of multiple linked fields
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:
coding:
type: array
items:
type: object
properties:
system:
type: string
default: http://terminology.hl7.org/CodeSystem/v3-RoleCode
code:
type: string
display:
type: string
enum:
- {code: DX,display: Diagnostics or therapeutics unit}
- {code: CVDX,display: Cardiovascular diagnostics or therapeutics unit}
The above is perfectly fine for OpenAPI Specification (in that it doesn't give an error), but there is no rendering of the code and display pairs
It would be useful to be able to document the link between separate field values that need to be consistent.
It would also be interesting to incorporate parent-child relationships between enum values (I'm not sure if this already exists or not). So, for example there could be type-code, type-display and type-definition values that need to be consistent as above, but also subtype-code, subtype-display and subtype-definition that depend on a given value of type-code (or its set of consistent values).
This could be made explicit by something like
enum:
enumgroup: {code, display}
- {code: DX,display: Diagnostics or therapeutics unit}
for the simple grouping above, or
enum:
enumgroup: {type-code, type-display, type-definition, {subtype-code, subtype-display, subtype-definition}}
for parent-child relationships. It allows simple parent-child relationships such as
enum:
enumgroup: {type, {subtype}}
and, for example grandparent, parent, child relationships too by further nesting.
If, for example, type-code was the only required field at the top level, it could be used as the "key" for the child set of values (allowing no values for the non-required top level fields, for example).
Edit: I'm not much of a fan of using nested object representation for parent-child relationships when the implementation may not want them as nested objects. Feel free to think of some other way of representing it if breaks norms. The problem here is that we are straddling the rendering and the implementation of the actual OpenAPI Specification too.
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
No files, tests, or entry points are named. Start by locating Swagger/OpenAPI enum rendering and review how arrays of objects are displayed. Done would require an agreed representation and rendering for linked enum fields, with any parent-child behavior defined; the issue leaves both design and scope unresolved.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- documentation, frontend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 20/100