Clarification about path template uri that may or not clash with other paths

[tomsfernandez]

Hi!. This is related to: #2753

Context: we have an OAS 3.0 api with two path objects: /v2 and /v2{param}. "Param" is a required parameter so in practice the second endpoint should always result in a different uri than the first one f.e: /v2 vs /v2test ("param" is parameterized with "test").

The question is: do these paths clash with each other or are they valid according to the spec? The only thing I found but that doesn't apply to this case completely is:

When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical

What would happen if instead of only two path objects, there were three:

• /v2
• /v2another
• /v2{param} (clashes with /v2another if param == another)

This is all without taking into account the different styles the template parameter could have.

How should API processors handle all these variations? It seems to me that this might be really error-prone for processors.

Here an API showcasing this:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: mytest
paths: 
  /v2:
    get:
      responses:
        "200":
          description: "___"
  /v2{params}:
    parameters:
      - in: path
        name: params
        required: true
        schema:
          type: string
    post:
      responses:
        "200":
          description: "_______"

[webron]

I don't see any problem with the described definition. With the case of /v2another and /v2{param} (clashes with /v2another if param == another), the definition of /v2another will take precedence because it's a specific case definition.

[rafalkrupinski]

Wouldn't /v2{param} clash with /v2 for param := ""?

[karenetheridge]

More specific path definitions always win over templated ones.

[tomsfernandez]

Great, thanks for the clarification!

[handrews]

Closing as answered.