path-parameters-on-items

Since 0.0.1 · In the rulesets: Recommended at warning, Strict at warning, All at error

This rule checks that path parameters are declared on the path item, not repeated on each of its operations.

Rule details

A placeholder belongs to the path, so its parameter belongs to the path item: declared once, it applies to every operation, and a change to its type or description happens in one place. Declared on the operations, the copies drift apart.

The rule reports One or more path parameters are missing or not defined in path item.

Examples

Good. One declaration for every operation of the path.

paths:
  /users/{userId}:
    parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
    get:
      summary: Get a user by ID
    delete:
      summary: Delete a user by ID

Bad. The same parameter, once per operation.

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
    delete:
      summary: Delete a user by ID
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string

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.rules has the details.

commands:
  lint:
    rules:
      path-parameters-on-items: off
Last updated on View as Markdown
Was this helpful?