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
Was this helpful?