paths-max-count

This rule ensures that an API does not define too many path items.

Rule Details

An API with more than a certain number of path items (e.g., 8) is considered too broad, which can make it difficult to maintain and understand.

The paths-max-count rule is designed to ensure that an API does not define too many path items. The rule works by counting the number of path items defined in the API. If the count exceeds the specified limit, the rule raises a warning.

Configuration

The configuration block is a single positive integer, which specifies the maximal number of path items in an API. The default value is 9.

Configuration Example

lint:
  rules:
    paths-max-count:
      - warning
      - 20

Examples

Good.

paths:
  /users:
    get:
      summary: Get all users
  /users/{userId}:
    get:
      summary: Get a user by ID
  /users/{userId}/posts:
    get:
      summary: Get a user's posts
  /posts:
    get:
      summary: Get all posts
  /posts/{postId}:
    get:
      summary: Get a post by ID
  /posts/{postId}/comments:
    get:
      summary: Get a post's comments
  /comments:
    get:
      summary: Get all comments
  /comments/{commentId}:
    get:
      summary: Get a comment by ID

Bad.

paths:
  /users:
    get:
      summary: Get all users
  /users/{userId}:
    get:
      summary: Get a user by ID
  /users/{userId}/posts:
    get:
      summary: Get a user's posts
  /posts:
    get:
      summary: Get all posts
  /posts/{postId}:
    get:
      summary: Get a post by ID
  /posts/{postId}/comments:
    get:
      summary: Get a post's comments
  /comments:
    get:
      summary: Get all comments
  /comments/{commentId}:
    get:
      summary: Get a comment by ID
  /tags:
    get:
      summary: Get all tags
  /tags/{tagId}:
    get:
      summary: Get a tag by ID

When Not to Use It

If your API does not have a limit on the number of path items it can define, you may not need to use this rule.

Compatibility

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