Linter rulesSwagger 2.0path-parameters-on-items

path-parameters-on-items

Since 0.9.0

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.

Configuration

None.

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.

When Not to Use It

You may disable this rule if your style guide prefers declaring path parameters on operations.

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x documents are linted by the OpenAPI linter, which has a rule of the same name.

Related rules

Further reading