paths-sorted

This rule checks URLs of path items defined in an OpenAPI schema, and warns if they are not placed in alphabetical order.

Rule Details

The paths-sorted rule is designed to ensure that the URLs of path items in an OpenAPI schema are placed in alphabetical order. This improves the readability and maintainability of the API specification.

Configuration

None.

Examples

Good. /users are placed after /products.

paths:
  /products:
    get:
      responses:
        "200":
          description: A list of products.
  /users:
    get:
      responses:
        "200":
          description: A list of users.

Good. /users/self is placed before /users/{id} as the more specific URL. This is similar to how route handlers are to be evaluated by most frameworks.

paths:
  /users/self:
    get:
      responses:
        "200":
          description: Information about current user.
  /users/{id}:
    get:
      responses:
        "200":
          description: Information about a user with given ID.

Bad. /users/self is placed after /users/{id}, differently from the way we write code in most frameworks.

paths:
  /users/{id}:
    get:
      responses:
        "200":
          description: Information about a user with given ID.
  /users/self:
    get:
      responses:
        "200":
          description: Information about current user.

When Not to Use It

We recommend to always enable this rule.

Compatibility

This rule is compatible with all OpenAPI 3.x versions.