redocly-cli/docs/rules/path-not-include-query.md

slug

slug
/docs/cli/rules/path-not-include-query

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:

rules:
  path-not-included-query: error

Examples

Given this configuration:

rules:
  path-not-included-query: error

Example of an incorrect path:

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

Example of a correct path:

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

Related rules

• path-parameters-defined
• configurable rules

Resources

• Rule source
• Paths docs
• Operation docs