Clarification on path templates that overlap another path

[lmsurpre]

Apologies if I'm missing something obvious, but I was trying to find a definitive statement that describes whether/how overlapping paths should work. For example, consider two paths like:

• /one
• /{template}

I browsed the spec but didn't see it. I browsed through Issue #574 and related issues, but those seem to cover more advanced cases.

I think its generally understood that this is supported (just look at http://petstore.swagger.io/) and that the concrete/fixed path(s) takes 'precedence' over the path template or path wildcard, but I was just looking for some re-assurance from the spec. Hopefully something I just missed?

[fehguy]

It's not supported (I believe) so perhaps the documentation needs updating. If the path mapping is not deterministic, the definition does little good.

@webron ?

[lmsurpre]

Wow, I'm glad I asked. Unless I'm missing something, the ubiquitous pet store example I mentioned uses this pattern in two different places:

• /pet/findByStatus
• /pet/{petId}
• /user/login
• /user/logout
• /user/{username}

This lead me to believe it is probably supported by all the tooling, even if not officially defined in the spec.

[DavidBiesack]

I hope this will continue to be allowed. It is not prohibited in paths object (or in 2.0 or the existing toos) so adding such a restriction now would be a breaking change. The mapping is deterministic, just as a regular expression (login|logout|.*) is valid (even if redundant). In the above example, this means a username of "login" or "logout" is not allowed. So one must be very careful about such overloading, but I don't think OAS should prohibit it.

[webron]

@lmsurpre Your initial idea is correct. A concrete path definition will take precedence over a templated path - there could never be ambiguity in path patching, so it's not an issue.

We can clarify the wording in the spec.

[webron]

Clarification merged.

[kinvaris]

It seems that tools to validate OAS, still seems to validate these endpoints, and do not mark them as ambiguous nor wrong.
It seems this does not only need work in the docs. But also in the schema validator.

Example endpoints with same methods:

/api/requests/{id}/{action}  # holds action as enum e.g. confirm-arrival, start-test, accept, ...
/api/requests/{id}/reject      # dedicated api endpoint, but not included in the wildcard api endpoint, because it has other parameters.

[handrews]

@kinvaris feel free to file an issue on the OAI/oascomply repository for anything you see tools handling strangely that you'd like the (still under development) compliance tool to check.