$ref replaces object on bundle, 3.1.0 spec not working when using siblings

[josefguenther]

Describe the bug

When calling redocly bundle, it actually is "smart" and replaces objects that use $ref. This causes it to ignore sibling items that are important in 3.1.0 spec.

To Reproduce When you have the following in a yaml file:

    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAlbum"

components:
  schemas:
    CreateAlbum:
      required: [ Description ]
      $ref: "#/components/schemas/Album"
    Album:
      type: object
      properties:
        Id:
          type: string
          readOnly: true
        Description:
          type: string

Now you use redocly bundle, it actually doesn't keep the CreateAlbum object. It is "smart" and just replaces that and uses the Album object directly. This causes sibling items (properties, required, etc) to be ignored. The output file looks like this:

    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Album'

OpenAPI description

In 3.1.0 spec, you can have sibling items next to $ref. Like this:

    CreateAlbum:
      required: [ Description ]
      $ref: "#/components/schemas/Album"

In 3.0.0 spec, you had to nest it with allOf, which works in redocly bundle and still keeps the object. Like this:

    CreateAlbum:
      required: [ Title ]
      allOf: 
        - $ref: "#/components/schemas/Album"

We shouldn't just ignore the object and replace it when using bundle. We should keep the original object.

Version

redocly --version    
1.17.1

[tatomyr]

Hi @josefguenther, your issue seems to be a duplicate of this issue. Please let me know if you think it's not.

BTW, I'm not certain it should take into account any other properties apart from description and summary, but feel free to add your considerations to that issue if needed.