paths-max-count

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

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.

The OpenAPI linter has a rule of the same name, paths-max-count, for OpenAPI 3.x documents.

Turn the rule off for APIs that are large by design.

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.

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.swagger has the details.

commands:
  lint:
    swagger:
      rules:
        paths-max-count: off

Related rules

Further reading

Was this helpful?