# paths-max-depth

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

A rule of the Swagger 2.0 linter, which reads Swagger 2.0 documents; OpenAPI 3 documents go to the OpenAPI linter. 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](/docs/linter/openapi/rules/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.

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