path-parameters-defined
Since 0.9.0 · fixed by --fix · In the rulesets: Recommended at error, Strict at error, All at error
This rule checks whether every parameter of a path template is declared as a path parameter.
Rule details
The Swagger 2.0 specification requires every template expression of a path
(such as {userId} in /users/{userId}) to correspond to a parameter with
in: path. Without it, tools do not know the type of the parameter and cannot
build request URLs.
The path-parameters-defined rule checks every operation and reports One or more path parameters are missing when a template expression of its path has
no matching in: path parameter, either among the parameters of the path item
or among the parameters of the operation. Parameter references ($ref) are
resolved; a parameter with the right name in another location (for example
in: query) does not count. Path parameters that do not appear in the
template are not reported.
The OpenAPI linter has a rule of the same name, path-parameters-defined, for OpenAPI 3.x documents.
undeclared path parameters violate the Swagger 2.0 specification.
Configuration
The options are an object with an optional defaultType property, which sets
the type of the parameters added by the automatic fix: string (default),
integer, number or boolean. Set it to null to disable the automatic
fix.
commands:
lint:
swagger:
rules:
path-parameters-defined:
- error
- defaultType: integer
Examples
Good. The path parameter is declared on the path item.
swagger: '2.0'
info:
title: Users
version: 1.0.0
paths:
/users/{userId}:
parameters:
- name: userId
in: path
required: true
type: string
get:
responses:
'200':
description: A single user.
delete:
responses:
'204':
description: The user was deleted.
Bad. The get operation declares userId as a query parameter and the
delete operation does not declare it at all.
swagger: '2.0'
info:
title: Users
version: 1.0.0
paths:
/users/{userId}:
get:
parameters:
- name: userId
in: query
type: string
responses:
'200':
description: A single user.
delete:
responses:
'204':
description: The user was deleted.
Automatic fixes
--fix appends the missing parameters, in the
order they appear in the path template, to the parameters of the path item.
Each added parameter has the form {name: <name>, in: path, required: true, type: <defaultType>}. No fix is offered when defaultType is null.
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:
path-parameters-defined: off