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

Related rules

Further reading

Was this helpful?