Display overriden description of discriminator

[kliput]

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:

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

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.

[kliput]

I've made a small fix for this issue: https://github.com/kliput/ReDoc/commit/62687d25e7a3980f23a98fd416eb866f6a7af1cc According to original example, it overrides type description property when subscheme have the description defined. I see that there is a fix for similiar problem: https://github.com/Redocly/redoc/issues/915 and the x-description is used.

Could you tell me, if my solution is compatible with OpenAPI, should I use x-discriminator, or there should be another solution?

[Gallaecio]

I think the new behavior is worst, but the old behavior was probably not ideal either.

Maybe the general description should be displayed before the drop-down box and the choice-specific description below the drop-down box.