Redocly / Redocly/redoc

Description sometimes not displayed when using allOf > $ref > oneOf

Open
#1,458 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

openapi
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:
redoc_missing_description

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

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.