Support adding model/schema descriptions to referenced properties

[dbedari-indeed]

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

[mathis-m]

From what I understand this is not a swagger-ui issue it is related to OpenAPI and therefore is not handled in swagger-js.

[dbedari-indeed]

I understand that proposing modifications to the schema are def OpenAPI territory, but isn't the actual rendering of the schema done by swagger? If so, wouldn't option (2) be a swagger-based change, and not openAPI?

Also, isn't swagger's implementation of the OpenAPI json somewhat different, i.e. it is a superset of the OpenAPI spec.

Edit: Sorry, I misspoke, the schema object is an extended subset of the openAPI schema object.

The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is an extended subset of the JSON Schema Specification Wright Draft 00.

I am not sure I know the development implications of maintaining this subset, but I am guessing it is non-trivial and something swagger wants to move away from, so I think maintaining different behavior for reference objects would be out of the question. Perhaps option (2) is the better choice, and can be done on the swagger side? Suggesting changes on the OpenAPI side would still require a change again by swagger to render the schema anyway, correct?