Linter rulesSwagger 2.0path-parameters-defined

path-parameters-defined

Since 0.9.0 · fixed by --fix

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.

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

When invoked with --fix, this rule 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.

When Not to Use It

We recommend to always enable this rule, since undeclared path parameters violate the Swagger 2.0 specification.

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