Support adding model/schema descriptions to referenced properties

Is your feature request related to a problem?

We would like to be able to add comments/descriptions to referenced objects.

Per the current OpenAPI spec for Component Objects, there currently seems to be no way to add (and have swagger render) description fields to components defined using linked Reference Objects instead of Schema Objects.

Only primitives types, object types with nested Schema Object definitions, or array types with items (Basically all Schema Object types) seem to allow for setting descriptions rendered by swagger. We tried to implement workarounds, but to us there seemed to be no way to wrap a Reference Object inside a Schema Object in such a way that swagger renders the description of the Schema Object as well as the referred to schema definition by the Reference Object - there is one exception to this, and that is the array types that support nesting $ref definitions inside items fields.

Example of current $ref behavior (we would like to add a description here):

...
    "resp": {
        "$ref": "#/definitions/indeed.soa.test.harness.SoaTestHarnessResponse" 
    }
...

Example of array types supporting descriptions:

...
    "resp": { 
        "description": "This array reference is special enough to warrant it's own description", 
        "items": { 
            "$ref": "#/definitions/indeed.soa.test.harness.SoaTestHarnessResponse" 
        },
        "type": "array"
    }
...

Describe the solution you'd like

If a schema element uses a reference to another schema object, we would like to be able to add a UI description to the referenced object. Not so opinionated on how the fix is implemented. Two simple ideas that come to mind are:

1. Add an optional field called description to $ref, which would render model/schema descriptions for the object being referred to.
2. Support adding a $ref to an object via some custom field (Basically nesting a ReferenceObject inside a SchemaObject), in the same way array types support adding $refs via items elements. For example, support having swagger render $ref inside items for object types.

If both of these are deemed unsavory, that's fine - we are open to other ideas.

Describe alternatives you've considered

We could copy down the schema for the referenced objects, but we would lose the topmost description element of the linked schema object itself; there is an argument to be made that comments on a referenced object may be different from the top-level comments on the object itself. Furthermore, duplicating fields is somewhat ugly, and leaves us with large schema files to lug around.

Additional context

N/A

Start by reproducing the two JSON examples in Swagger UI and compare how a direct $ref and an array items $ref are rendered. Trace the schema/reference rendering entry point, then evaluate an approach for displaying a property-level description without losing the referenced schema. Done means the requested description appears in the UI and existing reference rendering remains intact.