redocly-cli icon indicating copy to clipboard operation
redocly-cli copied to clipboard

Redocly bundle doesn't correctly render description $ref with $ref sibling

Open andrea3bianchi opened this issue 9 months ago • 1 comments

Describe the bug Not sure if it is expected but using description: $ref: "./description.md" together with a sibling $ref doesn't render properly, it just creates a description object with $ref Dereferencing also produces the same output Using version 1.28.5

Expected behavior I would expect it to properly render the reference as it would without a $ref sibling

Minimal reproducible OpenAPI snippet(if possible)

-- components/schemas/child.yaml --
type: object
additionalProperties: false
title: Child
description: child
properties:
  s:
    type: string
-- components/schemas/description.md --
Foo
-- components/schemas/parent.yaml --
type: object
properties:
  s: #renders fine
    description:
      $ref: ./description.md
    type: string
  childWithDescription: #renders fine
    description: local description
    $ref: ./child.yaml
  childWithAllOf: #renders fine
    description:
      $ref: ./description.md
    allOf:
      - $ref: ./child.yaml
  childWithReferenceDescription: #this is the one with issues
    description:
      $ref: ./description.md
    $ref: ./child.yaml
-- openapi.yaml --
openapi: 3.1.1
info:
  title: Test
  version: 1.0.0
paths:
  /parent:
    get:
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "./components/schemas/parent.yaml"

redocly bundle openapi.yaml output:

components:
  schemas:
    child:
      type: object
      additionalProperties: false
      title: Child
      description: Zxc
      properties:
        s:
          type: string
    parent:
      type: object
      properties:
        s:
          description: Foo
          type: string
        childWithDescription:
          description: local description
          $ref: '#/components/schemas/child'
        childWithAllOf:
          description: Foo
          allOf:
            - $ref: '#/components/schemas/child'
        childWithReferenceDescription:
          description:
            $ref: ./description.md
          $ref: '#/components/schemas/child'
        childWithReferenceDescriptionYaml:
          description:
            $ref: ./description.yaml
          $ref: '#/components/schemas/child'

The issue being with the last two, Foo gets correctly rendered in the other cases

andrea3bianchi avatar Feb 13 '25 19:02 andrea3bianchi

This is a bug indeed. Thanks for reporting!

tatomyr avatar Feb 14 '25 11:02 tatomyr

The fix has been released. @andrea3bianchi could you confirm it's fixed?

tatomyr avatar Nov 11 '25 10:11 tatomyr