parameters-unique

Since 0.0.1 · fixed by --fix

Check parameters of operations and path items and warn if they have duplicate parameters.

Rule Details

If an operation or a path item defines multiple parameters with the same location and name, this signals an error.

This parameters-unique rule checks parameters of every path item and every operation in OpenAPI schema and warns if any of them has parameters with the same name and location.

Configuration

None.

Examples

Good. Parameters are unique.

paths:
  /users/{id}:
    get:
      parameters:
        - name: id
          in: path
          description: The ID of the user to retrieve.
          required: true
          schema:
            type: string
        - name: with-relations
          in: query
          description: If true, also returns related resources.
          required: false
          schema:
            type: boolean

Good. While parameter names are identical, their locations are not.

paths:
  /users/{id}:
    get:
      parameters:
        - name: id
          in: path
          description: The ID of the user to retrieve.
          required: true
          schema:
            type: string
        - name: id
          in: query
          description: Controversial, but still OK.
          required: false
          schema:
            type: boolean

Bad. Duplicate parameter definitions lead to confusion, which most likely is an error.

paths:
  /users/{id}:
    get:
      parameters:
        - name: id
          in: path
          description: The ID of the user to retrieve.
          required: true
          schema:
            type: string
        - name: id
          in: path
          description: The ID of the user to retrieve.
          required: true
          schema:
            type: boolean

When Not to Use It

We recommend to always enable this rule.

Automatic fixes

When invoked with --fix, this rule removes a later duplicate only when its complete source definition is structurally identical to the first definition. Conflicting duplicate parameters remain manual.

Compatibility

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