parameters-unique
Since 0.9.0 · fixed by --fix · In the rulesets: Recommended at error, Strict at error, All at error
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.
The OpenAPI linter has a rule of the same name, parameters-unique, for OpenAPI 3.x documents.
duplicate parameters violate the Swagger 2.0 specification.
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
--fix 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.
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.swagger has the details.
commands:
lint:
swagger:
rules:
parameters-unique: off