paths-max-depth
Since 0.9.0 · In the rulesets: Recommended at warning, Strict at warning, All at error
This rule checks whether the paths of a Swagger 2.0 document are nested deeper than a configured maximum.
Rule details
Deeply nested paths are hard to read and remember, and often expose internal relationships between resources that consumers do not need to know about.
The paths-max-depth rule counts the non-empty segments of each path, path
template expressions included, and reports Path URL is too much nested (<path>) on the path item when the count exceeds the configured maximum (4 by
default). For example, /pets/{id}/toys has 3 segments. The root basePath
is not counted.
The OpenAPI linter has a rule of the same name, paths-max-depth, for OpenAPI 3.x documents.
Turn the rule off when the resource hierarchy of your API is inherently deep.
Configuration
A single positive integer: the maximum number of path segments. The default is 4.
commands:
lint:
swagger:
rules:
paths-max-depth: [warning, 3]
Examples
Good. With the default maximum of 4, the path has 3 segments.
swagger: '2.0'
info:
title: Pet Store
version: 1.0.0
paths:
/pets/{petId}/toys:
get:
parameters:
- name: petId
in: path
required: true
type: string
responses:
'200':
description: The toys of a pet.
Bad. With the default maximum of 4, the path has 6 segments.
swagger: '2.0'
info:
title: Pet Store
version: 1.0.0
paths:
/owners/{ownerId}/pets/{petId}/toys/{toyId}:
parameters:
- name: ownerId
in: path
required: true
type: string
- name: petId
in: path
required: true
type: string
- name: toyId
in: path
required: true
type: string
get:
responses:
'200':
description: A single toy.
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:
paths-max-depth: off