Paths and operations: Query String in Paths and recommendation

https://swagger.io/docs/specification/paths-and-operations/ under "Query String in Paths" mentions:

This also means that it is impossible to have multiple paths that differ only in query string, such as:

GET /users?firstName=value&lastName=value
GET /users?role=value

This is because Swagger considers a unique operation as a combination of a path and the HTTP method, and additional parameters do not make the operation unique. Instead, you should use unique paths such as:

GET /users/findByName?firstName=value&lastName=value
GET /users/findByRole?role=value

I cannot make sense of this recommendation, as in making me believe it is almost incorrect and should not be there.

Imagine if you extrapolate this suggesiton so you have name, role, occupation, country etc. Having multiple findBy is impossible especially the more combinations you have.

For me, this is completely logical and valid to filter by certain things:

GET /users?firstName=value&lastName=value
GET /users?role=value

It means I can add/remove firstName, role, occupation, country etc. as I see fit to only limit results that match all of my filters.

Start with the “Query String in Paths” section at swagger.io/docs/specification/paths-and-operations/ and review the surrounding OpenAPI guidance on paths, operations, and parameters. Compare the recommendation with the relevant specification rules and determine whether the wording needs clarification or correction; done means the documentation accurately explains valid query filtering and operation uniqueness.