To Allow specify (at least) description in response definition when $ref is used

[ratermir]

It would be very useful to be able to add (at least) description to the $ref in case of (at least) response part of the API specification.

It would allow me to specify generic reusable response that could be refined for every concrete use case. Because there are a lot of cases of responses that have the same structure, only the difference is the information why / when the error occurred.

Oxample of the use case:

In more generic perspective, it could be useful to allow to "override" some parts of references (examples, parameters ...).

[handrews]

For Schema Objects, this is addressed by PR #1977 for OAS 3.1

I'm not sure what the plan is for $ref outside of Schema Objects.

[handrews]

This should probably be tracked in #2099. While not technically a JSON Schema issue, it is an example of the sort of question that will come up once JSON Schema keywords are allowed adjacent to $ref in OAS 3.1.

[ratermir]

Originally I posted this request to the swagger editor group, but they redirected me here - they can't make such changes to this tool (= editor) if the schema says things different. That's why I posted it also here.

[handrews]

@ratermir yes, this is the correct repo.

@whitlockjc @webron more $ref fun that we should track for OAS 3.1. I think it falls under things we're already talking about.

[MikeRalphson]

PR: #2181