Swagger-ui: Allow reference siblings

[verschoof]

### Content & configuration

https://swagger.io/docs/specification/using-ref/#sibling

$ref and Sibling Elements

Any sibling elements of a $ref are ignored. This is because $ref works by replacing itself and everything on its level with the definition it is pointing at. Consider this example:

Swagger/OpenAPI definition:
yaml components: schemas: Date: type: string format: date DateWithExample: $ref: '#/components/schemas/Date' description: Date schema extended with a `default` value... Or not? default: 2000-01-01

In the second schema, the description and default properties are ignored, so this schema ends up exactly the same as the referenced Date schema.

Is your feature request related to a problem?

I'm always frustrated when swagger ignores my parameter fields when I give them together with an reference.

Describe the solution you'd like

I would like to see that you can override your reference.
In my case, I use a parameter, but only the description is different every time, so I would like to use the ref and my own description field.

So Code technically use the reference as base array and merge the properties of the parameter. The properties on the parameters should be leading.

I'm really wondering why you would ignore the rest of the parameter properties if you are using a reference, If I wouldn't need them, I would not put them :)

[hkosova]

You can use allOf as a workaround to _add_ extra attributes to a $ref (but not override existing attributes):

    DateWithExample:
      allOf:
        - $ref: '#/components/schemas/Date'
      description: Date schema extended with a `default` value.
      default: '2000-01-01'

I'm always frustrated when swagger ignores my parameter fields when I give them together with an reference.

$ref behavior is defined by the JSON Reference spec, which says:

Any members other than "$ref" in a JSON Reference object SHALL be ignored.

OpenAPI Specification and Swagger tools simply follow the JSON Reference specification. Here's a related discussion in the OpenAPI Specification repository:
https://github.com/OAI/OpenAPI-Specification/issues/556

[verschoof]

@hkosova Thanks for the link.

I've been reading, so if I'm correct they introduced a new concept applicators?
https://github.com/json-schema-org/json-schema-spec/blob/master/jsonschema-core.xml#L194

[hkosova]

@verschoof Sorry, I'm not familiar with the latest draft of JSON Schema.

OpenAPI Specification 3.0 uses JSON Schema Draft 5 (aka draft-wright-json-schema-00), so any JSON Schema features from later drafts first need to be officially introduced to the OpenAPI spec in order to make use of them in OpenAPI and Swagger tools.

[shockey]

Closing this, as $ref siblings would require a change to the OpenAPI Specification before it could be implemented here - @verschoof, consider opening a ticket for this over at https://github.com/OAI/OpenAPI-Specification/issues/new 😄