paths-unique

This rule checks whether URLs of path items are unique.

Rule Details

Unique URLs prevent confusion and misinterpretation of the API’s structure.

The paths-unique rule is designed to ensure that all URLs of path items are unique. URLs that differ only in parameter names, like /users/{id} and /users/{userId}, are treated as identical.

Configuration

None.

Examples

Good.

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
  /users/{userId}/posts:
    get:
      summary: Get a user's posts

Bad.

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
  /users/{id}:
    get:
      summary: Get a user by ID

When Not to Use It

If your API does not use path parameters or if you have other means of ensuring URL uniqueness, you may not need to use this rule.

Compatibility

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