path-parameters-on-items
Since 0.9.0 · In the rulesets: Recommended at warning, Strict at warning, All at error
This rule checks whether path parameters are declared on path items rather than on individual operations.
Rule details
A path parameter belongs to the path, so every operation of a path item shares
it. Declaring it once in the parameters of the path item avoids repeating
the same definition in every operation and keeps the definitions consistent.
The path-parameters-on-items rule reports One or more path parameters are missing or not defined in path item for every path item when a template
expression of its path has no matching in: path parameter in the path
item’s own parameters. Parameters declared on operations do not count.
Parameter references ($ref) are resolved.
The OpenAPI linter has a rule of the same name, path-parameters-on-items, for OpenAPI 3.x documents.
Turn the rule off if your style guide prefers declaring path parameters on operations.
Examples
Good. The path parameter is declared on the path item.
swagger: '2.0'
info:
title: Pet Store
version: 1.0.0
paths:
/pets/{petId}:
parameters:
- $ref: '#/parameters/petId'
get:
responses:
'200':
description: A single pet.
parameters:
petId:
name: petId
in: path
required: true
type: string
Bad. The path parameter is declared on the operation.
swagger: '2.0'
info:
title: Pet Store
version: 1.0.0
paths:
/pets/{petId}:
get:
parameters:
- name: petId
in: path
required: true
type: string
responses:
'200':
description: A single pet.
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-on-items: off