paths-sorted

Since 0.9.0 · fixed by --fix · In the rulesets: Strict at error, All at error

This rule checks whether the paths of a Swagger 2.0 document are sorted.

Rule details

Sorted paths make a large document easier to navigate and keep diffs small when paths are added.

The paths-sorted rule walks the entries of the root paths object in the order they appear in the document and reports Paths are not sorted: <path> for every path that is not greater than the previous one. Paths are compared character by character (byte order), so /Pets sorts before /pets and /pets before /pets/{id}.

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

Turn the rule off when paths are intentionally grouped in another order, for example by resource or by workflow.

Examples

Good. The paths are sorted.

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

Bad. /owners is listed after /pets.

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.

Automatic fixes

--fix reorders the entries of the paths object so that the paths are sorted in byte order.

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-sorted: off

Related rules

Further reading

Was this helpful?