Linter rulesSwagger 2.0paths-max-count

paths-max-count

Since 0.9.0

This rule checks whether a Swagger 2.0 document defines more paths than a configured maximum.

Rule Details

A large number of paths may indicate that an API covers too many concerns and could be split into smaller, more focused APIs.

The paths-max-count rule counts the entries of the root paths object and reports Too many paths found (<count>), maximum number is <maximum> on the document root when the count exceeds the configured maximum (8 by default). Each path counts once, whatever the number of its operations.

Configuration

A single positive integer: the maximum number of paths. The default is 8.

commands:
  lint:
    swagger:
      rules:
        paths-max-count: [warning, 20]

Examples

Good. With a maximum of 2, the document defines 2 paths.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets:
    get:
      responses:
        '200':
          description: A list of pets.
  /owners:
    get:
      responses:
        '200':
          description: A list of owners.

Bad. With a maximum of 2, the document defines 3 paths.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets:
    get:
      responses:
        '200':
          description: A list of pets.
  /owners:
    get:
      responses:
        '200':
          description: A list of owners.
  /visits:
    get:
      responses:
        '200':
          description: A list of visits.

When Not to Use It

You may disable this rule for APIs that are large by design.

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.

Related rules

Further reading