Description
Paths such as /users/{id} and /users/{ids} have the same structure and differ only in variable names, so they describe the same URL pattern. OpenAPI 3.0 disallows these duplicates, and the correspondence between documentation and routing can become unclear.
Potential impact
Documentation, tests and SDKs may confuse operations or generate paths that do not match the server’s routing.
Remediation
Place different methods for the same resource under one path. If resources are genuinely different, distinguish their path structure and update implementations and clients accordingly. Define a matching required path parameter for every variable.
Examples
These OpenAPI 3.0 excerpts compare path structure. They omit info and the path parameter definitions required for each variable.
Before
openapi: 3.0.0
paths:
"/users/{id}":
get:
responses:
"200":
description: OK
"/users/{ids}":
get:
responses:
"200":
description: OK
After
openapi: 3.0.0
paths:
"/users/{id}":
get:
responses:
"200":
description: OK
"/user-groups/{id}":
get:
responses:
"200":
description: OK
The before paths differ only in variable names and share a pattern. The after example separates users from user-groups. Apply that change only when the actual API distinguishes those resources.