Openapi-specification: Clarify statement about `Reference obects` in `Responses object`

Created on 31 Aug 2018  路  3Comments  路  Source: OAI/OpenAPI-Specification

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?

$ref

Most helpful comment

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.

All 3 comments

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.

Was this page helpful?
0 / 5 - 0 ratings