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