Field "description" values are usurped by the schema's definition description (used via Redoc)

[davetransom]

Descriptions for fields are incorrectly converted from swagger 2.0 for complex objects (dependency in Redoc) i.e. it uses the description of the object, instead of the actual field.

Checklist

• Conversion: I have checked my source definition is valid OpenAPI 2.0
• Conversion: On valid OpenAPI 2.0 input, the conversion looks wrong
• Resolver issue (maybe)

Detailed Description

Hi, I've shown up here as Redoc uses swagger2openapi to convert legacy swagger 2.0 into OpenAPI before rendering.

I've come across an issue where the descriptions on fields are being replaced by the fields on the object definition where structured objects are being used e.g.

"order": {
  "orderId": 123,
  ...
  "client": {
    "code": "ABC123",
    "name": "Company 1"
  },
  ...
}

This concerns the "description" that the "client" field ends up with in the converted OpenAPI spec.

Instead of the field's description:

"The client Org this order has been placed under."

which is helpful to the user, however the resultant description is:

"A generic organisation reference (code, name and optional type)."

I did have a poke around in the source, but couldn't come up with a simple explanation. I'm happy to help with a pull request in the hopes it helps other users of this tool (and redoc).

Visual Comparison

1. how it displays:
   
2. expected display:
   

Here is a condensed swagger 2.0 sample to illustrate: sample.json.txt

(edit: hit ENTER accidentally after only entering the title🤦)

[MikeRalphson]

By default swagger2openapi follows the OpenAPI 2.0 / 3.0 spec which says that all other properties which are siblings to a $ref are ignored.

There is an option (CLI and programmatic) called refSiblings which defines the mode to handle $ref's with sibling properties, the valid values are remove (the default), preserve, and allOf, the last of which wraps the $ref and the sibling properties into an allOf array.

I don't know if Redoc specifies or exposes this option, or even if it uses a version of swagger2openapi recent enough to have it. Maybe @RomanHotsiy knows off-hand?

[MikeRalphson]

refSiblings was introduced in swagger2openapi v5.0.0, and Redoc uses v7.0.6 so it could make use of this feature. https://github.com/Redocly/redoc/search?q=refSiblings shows it doesn't alter the default.

[RomanHotsiy]

@davetransom open an issue in Redoc repo plz. I believe we don't use refSiblings flag.

@MikeRalphson I think you can close this.

[MikeRalphson]

Thanks both!