paths-sorted
Since 0.0.1 · fixed by --fix · In the rulesets: Strict at error, All at error
This rule checks that the paths of a document are in alphabetical order.
Rule details
A sorted paths section is a table of contents: the reader finds /users/{id} next to /users
and sees at a glance which resources the API has. In the order of a byte comparison, a literal
segment such as /users/self comes before a placeholder such as /users/{id}, which is also the
order in which most routers try the routes.
The rule reports Paths are not sorted: ... on each path that comes before its predecessor.
Examples
Good. /products before /users.
paths:
/products:
get:
responses:
"200":
description: A list of products.
/users:
get:
responses:
"200":
description: A list of users.
Good. The literal /users/self before the placeholder /users/{id}.
paths:
/users/self:
get:
responses:
"200":
description: The current user.
/users/{id}:
get:
responses:
"200":
description: The user with the given ID.
Bad. /users/self after /users/{id}.
paths:
/users/{id}:
get:
responses:
"200":
description: The user with the given ID.
/users/self:
get:
responses:
"200":
description: The current user.
Automatic fixes
--fix reorders the path items. Nothing inside a path item changes.
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-sorted: off