To Allow specify 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 (at least) response part of the API specification.
It would allow me to specify generic response that could be refined for every 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.
I know that it is not allowed by the specification, byt by my opinion (and according my experiences) it helps to simplify the API and make documentation more readable and useful.

One example is here:

[webron]

As you've mentioned, this not supported by the spec, so there's nothing we can really do about it at the moment. Please follow https://github.com/OAI/OpenAPI-Specification/ for updates, but know that in the upcoming OpenAPI 3.1.0 there's a good chance this will change and you'll be able to do just that. 🤞