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

Related rules

Further reading

Was this helpful?