Redocly / Redocly/redoc

Field descriptions ignored and overwritten by referenced objects

Open
#835 2 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Take the case of the swagger below where descriptions have been added to give context to multi-purpose objects such as Date.

    "boardingIdentityDetails": {
      "type": "object",
      "properties": {
        "identityDocument": {
          "$ref": "#/definitions/boardingIdentityDocument"
        },
        "issuingCountry": {
          "type": "string",
          "description": "The two digit ISO 3166 country code of the country of the travel document issuing authority."
        },
        "nationality": {
          "type": "string",
          "description": "The two digit ISO 3166 country code of the traveler's nationality."
        },
        "documentNumber": {
          "type": "string",
          "description": "The number or other unique identifying reference of the traveler's document."
        },
        "dateOfBirth": {
          "$ref": "#/definitions/ioDate",
          "description": "The date of birth as marked on the traveler's identity document."
        },
        "gender": {
          "$ref": "#/definitions/ioGender",
          "description": "The gender as marked on the traveler's identity document."
        },
        "issuedDate": {
          "$ref": "#/definitions/ioDate",
          "description": "The issue date of the traveler's identity document."
        },
        "expiryDate": {
          "$ref": "#/definitions/ioDate",
          "description": "The expiry date of the traveler's identity document."
        }
      },
      "description": "Details of document used to identify the traveler's identity."
    }

When rendered, these descriptions (and also titles) are ignored and referenced object's descriptions are used instead.

Should there not be a hierarchy, making it possible to override a referenced object's title and description?

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

Start by reproducing the provided Swagger example in Redoc and trace how referenced schemas supply titles and descriptions during rendering. Add coverage for property-level overrides and verify that local titles and descriptions take precedence over those on referenced objects.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.