The description of Responses object (for both fixed and patterned fields) reads:
A Reference Object can link to a response that the OpenAPI Object's components/responses section defines.
The use of the word "can" is particularly misleading here. Does this mean MAY or MUST?
That is, can any reference object be used, or is this implying a constraint that the reference object has to be of the form #/components/responses when used in a responses object?
Will change to "The Reference Object MUST link to an OpenAPI Response Object."
I think this change will allow a $ref to a response object within the "responses" of another operation in the API doc. Is that the desired result? If so, should we allow the same kind of behavior for parameters? I.e., rather than
The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's components/parameters.
Should we say
The list can use the Reference Object to link to an OpenAPI Parameter Object
?
Yes, I'll try to mop up all similar wording. There would be no reason to disallow a $ref to another operation's responses object, but re-use under components/schemas is more common and readable.
Most helpful comment
Yes, I'll try to mop up all similar wording. There would be no reason to disallow a
$refto another operation'sresponsesobject, but re-use undercomponents/schemasis more common and readable.