unambiguous-response-codes
Since 0.0.1 · In the rulesets: Recommended at error, Strict at error, All at error
This rule checks that no operation declares both a range, such as 2XX, and a code of that range,
such as 204.
Rule details
OpenAPI gives a code precedence over its range, but a reader does not know that, and a response
declared twice, once as 204 and once as part of 2XX, raises the question which description,
body and headers apply. Tools differ too: a mock server picks one, a generated client may
deserialize the other.
The rule reports Operation response codes are ambiguous on the response that overlaps an
earlier one. Turn it off when the API treats a range as the default and a code as its override on
purpose.
Examples
Good. A range and a code of another range.
paths:
/users:
get:
responses:
"103":
description: Early hints for the resources the page needs.
"2XX":
description: A list of users.
Bad. 204 is in 2XX.
paths:
/users:
get:
responses:
"2XX":
description: A list of users.
"204":
description: No content.
Turn it off or change its severity
In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.rules has the details.
commands:
lint:
rules:
unambiguous-response-codes: off