API Genie

This rule ensures that path item URLs do not contain too many segments.

Rule Details

Path URLs with more 4 or 5 segments most often mean that the API is too complex. Limiting the number of segments in a URL enhances the readability and maintainability of the API’s structure.

The paths-max-depth rule is designed to ensure that all path item URLs do not contain too many segments. A segment is part of a URL bounded by forward slashes, or the start or end of strings.

Configuration

The configuration block is a single positive integer, which specifies the maximal number of segments in an URL. The default value is 3.

Configuration Example

lint:
  rules:
    paths-max-depth:
      - warning
      - 6

Examples

Good.

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID

Bad.

paths:
  /users/{userId}/posts/{postId}/comments/{commentId}:
    get:
      summary: Get a comment of a post of a user

When Not to Use It

If your API does not have a limit on the number of segments in its path item URLs, you may not need to use this rule.

Compatibility

This rule is compatible with all OpenAPI 3.x versions.