Description sometimes not displayed when using allOf > $ref > oneOf
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 25.9k
- Forks
- 2.4k
- Avg merge
- 13h 10m
- Merged PRs (30d)
- 4
Description
Some of my descriptions just won't show, although others with identical schema do.
Redoc: 2.0.0-rc.45
Redoc-cli: 0.9.13
For example these two properties are virtually identical but for the "lower" and "upper" in the description:
{
"type": "object",
"properties": {
"effortFrom": {
"allOf": [{"$ref": "./NumberSchema.json#/definitions/decimal8dot2Nullable"}],
"description": "The lower limit of effort in hours - used for the 'effortFromTo' billing type."
},
"effortTo": {
"allOf": [{"$ref": "./NumberSchema.json#/definitions/decimal8dot2Nullable"}],
"description": "The upper limit of effort in hours - used for the 'effortFromTo' billing type."
}
}
}
Yet, I cannot get the description to show for the latter:
For your reference, the NumberSchema.json looks like this:
{
"definitions": {
"decimal8dot2": {
"type": "number",
"minimum": 0,
"maximum": 1000000,
"exclusiveMaximum": true,
"multipleOf": 0.01
},
"decimal8dot2Nullable": {
"oneOf": [
{"type": "null"},
{"$ref": "#/definitions/decimal8dot2"}
]
}
}
}
Is redoc caching something there while merging? Or re-using object references where it should not?
I have other props where the description is missing, also with an allOf-oneOf construct due to $ref + description. I've tried putting the description inside the allOf, and while this gives me the description when expanding the property on the page, it still does not show it in the table directly.
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
Reproduce the missing description with the supplied schemas in Redoc 2.0.0-rc.45 or redoc-cli 0.9.13, then trace the schema rendering path for allOf, $ref, and oneOf descriptions. Done means the property description appears in the table as well as when the property is expanded, without breaking the comparable effortFrom case.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- documentation, frontend
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100