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
Was this helpful?