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

Related rules

Further reading

Was this helpful?