paths-max-depth (Swagger 2.0 linter rule)

paths-max-depth

Since 0.9.0

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.

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.

When Not to Use It

You may disable this rule when the resource hierarchy of your API is inherently deep.

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.