Linter rulesSwagger 2.0parameters-unique

parameters-unique

Since 0.9.0 · fixed by --fix

This rule checks whether the parameter lists of a Swagger 2.0 document contain duplicates.

Rule Details

The Swagger 2.0 specification requires a parameter list not to contain duplicate parameters, where a parameter is identified by the combination of its name and its location (in). With duplicates it is unclear which definition applies.

The parameters-unique rule checks the parameters of every path item and of every operation separately, and reports Duplicate parameter name '<name>' in location '<location>' for every parameter that repeats the name and location of an earlier parameter of the same list. Parameter references ($ref) are compared by the parameter they point to; unresolved references are ignored. A parameter with the same name in a different location (for example a query parameter and a header both named id) is not a duplicate.

Configuration

None.

Examples

Good. The parameters differ by name or location.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets:
    get:
      parameters:
        - name: id
          in: query
          type: string
        - name: id
          in: header
          type: string
      responses:
        '200':
          description: A list of pets.

Bad. The inline limit parameter duplicates the referenced one.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets:
    get:
      parameters:
        - $ref: '#/parameters/limit'
        - name: limit
          in: query
          type: string
      responses:
        '200':
          description: A list of pets.
parameters:
  limit:
    name: limit
    in: query
    type: integer

Automatic fixes

When invoked with --fix, this rule removes a duplicate parameter from its list when it is structurally identical to the first parameter with the same name and location (references are compared by their targets). Duplicates that differ from the first parameter are reported but not fixed, since the rule cannot tell which definition is the right one.

When Not to Use It

We recommend to always enable this rule, since duplicate parameters violate the Swagger 2.0 specification.

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x documents are linted by the OpenAPI linter, which has a rule of the same name.

Related rules

Further reading