path-params
Path Parameters are pretty easy to get wrong.
Sometimes, they can be defined, but never used, or used but never defined. Sometimes they are duplicated, or set to required, but then are not defined.
There is a whole raft of issues that can appear with Path Parameters, so this rule is one of the more complex ones.
Why did this violation appear?
An operation has used path parameters, but has incorrectly implemented them.
What is this rule checking for?
- Unique path templates across HTTP methods
- Duplicate parameter names in paths
- Unknown (un-named) parameters
- Compliance with ‘required’ state
- All parameters must be defined
Bad examples
These paths have equivalent templates, even though their HTTP methods differ.
paths:
/pets/{id}:
parameters:
- {name: id, in: path, required: true, schema: {type: string}}
get:
responses:
'200': {description: Pet found}
/pets/{name}:
parameters:
- {name: name, in: path, required: true, schema: {type: string}}
delete:
responses:
'204': {description: Pet deleted}
Changed in v0.42.0
In v0.41.0 and earlier, equivalent path templates were allowed when their HTTP methods differed.
From v0.42.0, path-params reports an error for equivalent templates across methods, with one finding per duplicate path. For example, GET /pets/{id} and DELETE /pets/{name} conflict. Put both operations under one path and use the same parameter name.
Good example
Put both operations under one path and use the same parameter name.
paths:
/pets/{id}:
parameters:
- {name: id, in: path, required: true, schema: {type: string}}
get:
responses:
'200': {description: Pet found}
delete:
responses:
'204': {description: Pet deleted}
Missing parameters (in path, but not defined)
paths:
/pizza/{type}/{toppings}:
parameters:
- in: path
name: type
get:
'200':
...
Using invalid required type
paths:
/musical/{melody}/{beats}:
parameters:
- in: path
name: melody
required: NOT_VALID_SHOULD_BE_BOOL
get:
parameters:
- in: path
name: beats
required: true
Parameter has been defined multiple times
paths:
/musical/{melody}/{beats}:
parameters:
- in: path
name: melody
- in: path
name: melody
get:
parameters:
- in: path
name: beats
- in: path
name: beats
How do I fix this violation?
Ensure all path params are used, they are unique and accounted for.
Spectral Equivalent
The rule is equivalent to path-params