Redocly / Redocly/redoc

Display overriden description of discriminator

Open
#1,382 2 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Hello,

Our documentation have a Caveat scheme with discriminator named type, and number of schemes inheriting from the Caveat, eg. time, ip, asn.

The Caveat has description of type field:

properties:
  type:
    type: string
    description: Type of the caveat

Every of the sub-scheme has its own description of the type field, eg.

  properties:
    type:
      type: string
      enum: [time]
      x-discriminator-value: "time"
      description: |
        Time caveat - limits the token's validity in time.

In 1.22.3 version of ReDoc, selecting the sub-scheme caused to show its own description of type field in request body schema:
obraz
obraz

In 2.x version of ReDoc, only the description defined in Caveat is show, no matter which type is selected:
obraz
obraz

Is this a missing feature from 1.x or it's possible my schema is incompatible with new ReDoc?

I'd love to see this supported in 2.x.

Edit 1: There is a similiar issue, but I don't know if it's exactly the same: https://github.com/Redocly/redoc/issues/752

Edit 2: What is interesting, we can change type of type property eg. from string to number, and then field type changes when switching time to ip.

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

Reproduce the reported schema in ReDoc 2.x and compare the selected discriminator subtype with the base Caveat schema. No source file or test is named in the issue, so locate the discriminator rendering path and add coverage showing that the subtype's type-field description is displayed when switching between time and ip.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.