path-not-include-query

Path should not include query parameters. The query parameters should be defined on the PathItem or Operation.

OAS Compatibility
2.0
3.0
3.1

API design principles

Don't put query string items in the path, they belong in parameters with in: query. This rule is not opinionated. Its root cause is inexperience with OpenAPI (no holy war here).

Configuration

Option Type Description
severity string Possible values: off, warn, error. Default off (in recommended configuration).

An example configuration:

Copy
Copied
rules:
  path-not-included-query: error

Examples

Given this configuration:

Copy
Copied
rules:
  path-not-included-query: error

Example of an incorrect path:

Copy
Copied
paths:
  /customers?id={id}:
    get:
      parameters:
        - name: id
          in: query
          required: true

Example of a correct path:

Copy
Copied
paths:
  /customers/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          description: The customer's ID.

Related rules

Resources