paths-sorted (Swagger 2.0 linter rule)

paths-sorted

Since 0.9.0 · fixed by --fix

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}.

Configuration

None.

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

When invoked with --fix, this rule reorders the entries of the paths object so that the paths are sorted in byte order.

When Not to Use It

You may disable this rule when paths are intentionally grouped in another order, for example by resource or by workflow.

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x documents are linted by the OpenAPI linter, which has a rule of the same name.