paths-specificity-order

When multiple paths can match the same request in routing or mocking tools, declaration order can become observable. A static path segment is more specific than a templated segment, so the more specific path should appear first.

For example, /permissions/all should be declared before /permissions/{userId} for the same HTTP method.

Why did this violation appear?

A more specific path was declared after a templated path that could also match the same request. This can lead to incorrect handler selection in tools like MSW, Express, and generated mock servers.

What is this rule checking for?

This rule checks overlapping paths that:

• share at least one HTTP method
• have the same number of path segments
• first differ at a position where one path uses a static segment and the other uses a path parameter

If the later path is more specific, the rule reports that it should be declared earlier.

Bad example

paths:
  /api/authentication/v1/permissions/{userId}:
    get:
      description: Get permissions for a specific user.
  /api/authentication/v1/permissions/all:
    get:
      description: Get all permissions for the current user.

Good Example

paths:
  /api/authentication/v1/permissions/all:
    get:
      description: Get all permissions for the current user.
  /api/authentication/v1/permissions/{userId}:
    get:
      description: Get permissions for a specific user.

How do I fix this violation?

Move the more specific path above the overlapping templated path for the same HTTP method. In practice, static segments should be declared before path parameters when both shapes could match the same request.