unambiguous-response-codes

This rule checks for operations that define responses for both a generic code (like 2XX) and a specific code in the same range (like 204).

Rule Details

When an operation defines responses for both “generic” code, such as 2XX, as well as for the specific code from the same range, such as 204, it is unclear which one should be used.

The unambiguous-response-codes rule is designed to prevent such situations. It ensures that operations do not define responses for both generic code and specific code in the same range. If such an operation is found, the rule raises an issue.

Configuration

None.

Examples

Good. Operation defines both generic and specific responses, but they fall into different ranges.

paths:
  /users:
    get:
      responses:
        "103":
          description: Returns preloading hints.
        "2XX":
          description: A list of users.

Bad.

paths:
  /users:
    get:
      responses:
        "2XX":
          description: A list of users.
        "204":
          description: No Content.

When Not to Use It

If your company decides to treat generic responses as defaults, and specific responses as overrides to that defaults.

Compatibility

This rule is compatible with all OpenAPI 3.x versions.