paths-max-count

Since 0.0.1 · In the rulesets: Recommended at warning, Strict at warning, All at error

This rule checks that a document declares at most 8 paths, or the number configured.

Rule details

A document with many paths is several APIs in one file: a reader cannot keep it in view, and a change to one part is a release of all of them. The limit is a prompt to split the document along the lines of the resources, not a property of the server.

The rule reports Too many paths found (...), maximum number is ... once, on the document. The default of 8 is low on purpose; set the limit that fits the API, or turn the rule off for an API that is one document by design.

Configuration

A positive integer: the number of paths allowed. 8 by default.

Configuration example. Up to 20 paths.

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

Examples

Good. Eight paths.

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. Ten paths with the default limit.

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

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.rules has the details.

commands:
  lint:
    rules:
      paths-max-count: off
Was this helpful?