OpenAPI 3.1: Missing description when $ref used

[daniilguit]

Describe the bug
OpenAPI 3.1 brings JSONSchema feature that allows using $ref with other attributes (e.g. "description")
redoc as of 2.0.0-rc.56 it ignores description (inheriting it from refed type)

**Minimal reproducible OpenAPI snippet
/test -> response -> .testAttr should have description "Overriden description", but currently has "Refed description"

{
      "openapi": "3.1.0",
      "info": {
        "title": "AA",
        "version": "1.0"
      },
      "paths": {
        "/test": {
          "get": {
            "operationId": "test",
            "responses": {
              "200": {
                "content": {
                  "application/json": {
                    "schema": {
                      "type": "object",
                      "properties": {
                        "testAttr": {
                          "description": "Overriden description",
                          "$ref": "#/components/schemas/Test"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
      },
      "components": {
        "schemas": {
          "Test": {
            "type": "object",
            "description": "Refed description"
          }
        }
      }
    }

Screenshots

[madsodgaard]

I am facing the same issue when previewing the docs with openapi-cli 1.0.0-beta.61, also occurs with the required attribute.

[daniilguit]

@Marshevskyy : Thanx a lot for fixing this issue! It was a real deal breaker for us. Can't wait for the new release.

[Marshevskyy]

np @daniilguit. we are planning to release it today

[madsodgaard]

@Marshevskyy Yea, thanks a lot! How does the versioning between openapi-cli and this package work? Does it also require a new release of openapi-cli to get this fix in openapi preview-docs?

[RomanHotsiy]

@madsodgaard yes. We'll do it too.

[RomanHotsiy]

cc @AlexVarchuk

[tigerinus]

np @daniilguit. we are planning to release it today

Is this included in https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js?

We are still experiencing the same problem where description is missing in each schema.

Thanks!

[AlexVarchuk]

@tigerinus very weird. which version openApi you use? Do you use $ref schema with description?

[tigerinus]

@AlexVarchuk

It's using "https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js" in the HTML.

OpenAPI example:

    Customer:
      description: |
        Customer information, including contact information for booking order related issues
      allOf:
        - $ref: "#/components/schemas/Person"
        - properties:
            phoneCountryCode:
              type: string
              description: |
                Country calling code defined by ITU, starting with international dialing prefix `+`
              example: "+1"
            phoneNumber:
              type: string
              description: |
                Phone number including area code without any punctuation
              example: "1234567890"
            email:
              type: string
              example: "peter_parker@yahoo.com"

Rendered Result:

[RomanHotsiy]

@tigerinus must be CDN caching. Try again plz.

[tigerinus]

@tigerinus must be CDN caching. Try again plz.

@RomanHotsiy I thought that was the reason so I did hard reset the browser everytime I test it. Unfortunately it's still the case. Can you repro it locally?

[atruskot]

Still able to reproduce this issue in redoc-cli@0.13.16. Seeing the base description rather than the sibling/overridden one. Will see the sibling description if the base has no description. The issue isn't specific to description, any base attribute will render if it exists. So base examples can't be overridden either, for example.

[bvisness]

Seeing this in v2.0.0-rc.72 as well, specifically for a property of an object:

# in a request definition...
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  settings:
                    $ref: "#/components/schemas/ReffedObject"
                    description: |
                      This should override the referenced description but it does not!

# elsewhere...
    ReffedObject:
      type: object
      description: |
        This is the base description, and the one I am seeing in Redoc.

I have seen description override a referenced description in a oneOf, but not here...