swagger-api / swagger-api/swagger-ui

Rendering enum of multiple linked fields

Open
#7,260 1 comment 1 reaction 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:

         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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.