# paths-max-depth

Source: https://apigenie.pl/docs/linter/swagger/rules/paths-max-depth

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.

```yaml
commands:
  lint:
    swagger:
      rules:
        paths-max-depth: [warning, 3]
```

## Examples

**Good**. With the default maximum of 4, the path has 3 segments.

```yaml
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.

```yaml
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.