Equivalent paths are not allowed even thogh the path + verb combination is different

[cskru]

Paste this spec in https://editor.swagger.io:

info:
  title: Server
  version: 1.0.0

host: 'localhost:8000'
basePath: /
produces:
  - application/json

schemes:
  - http

swagger: '2.0'
paths:
  
  '/path/{paramName}':
    get:
      summary: Get paramName
      parameters:
        - name: paramName
          in: path
          required: true
          type: string
      responses:
        '200':
          description: Success
  '/path/{someOtherParamNameButTheVerbIsPut}':
    put:
      summary: Update paramName
      parameters:
        - name: someOtherParamNameButTheVerbIsPut
          in: path
          required: true
          type: string
      responses:
        '200':
          description: Success

Though path+verb combinations are different, it throws error.
This is not expected at all!

[hkosova]

TL;DR: This is a limitation of the OpenAPI Specification and not a Swagger Editor issue.

The error means that these paths

/path/{paramName}
/path/{someOtherParamNameButTheVerbIsPut}

are considered identical and therefore invalid. They are identical because there's no way to tell if /path/foo corresponds to /path/{paramName} or /path/{someOtherParamName}. The parameter name alone does not make the path unique.

What you can do is define a single path /path/{paramName} with 2 operations get and put:

paths:
  /path/{paramName}:
    get:
      ...
    put:
      ...

This limitation has been previously discussed in the OpenAPI Specification repository here:
OAI/OpenAPI-Specification#576
OAI/OpenAPI-Specification#788

If you want to change the path matching behavior, file an enhancement request with OpenAPI Specification:
https://github.com/OAI/OpenAPI-Specification/issues

[webron]

What @hkosova said.

[cskru]

I understand what you have to say @hkosova and thank you for the response.

Regarding your comment:

there's no way to tell if /path/foo corresponds to /path/{paramName} or /path/{someOtherParamName}

There sure is a way and that is why I created this issue. We can differentiate them by specifying different verbs: put and get say.

It is fair to have ['/path/{paramName}' get] and [/path/{someOtherParamNameButTheVerbIsPut}' put]

I mean, the key should be path + verb combination, not the path alone.

I am not asking for something like this:
['/path/{paramName}' get] and [/path/{someOtherParamNameButTheVerbIsPut}' get]
This definitely causes conflict.

But I don't understand why there is an issue when the verb + path combinations are different.

My server is happy and has no qualms about it. Then why should the documentation have issues? :-)
Hope you understand the point.

#854
@webron , please refer this comment where you mention verb + path uniquely identifies an operation:
#854 (comment)

Swagger already is awesome. If these constraints are solved, it'll be more awesome to use. :-)

I strongly encourage you to reopen this issue.

[webron]

They are not different. /path/{pathName} and /path/{whatever} are equivalent not matter what. That's how the spec regards it, and that's pretty much it. The fact that your server doesn't have issues with it, doesn't mean the spec doesn't. The spec doesn't allow plenty of things different server implementations do.

[nickdnk]

I have this problem as well. Consider this:

I want to add multiple entries all under a specific date:

POST /something/{date}

Each entry gets and ID, which means I can delete or update individual entries like this:

DELETE /something/{id}
PATCH /something/{id}

{id} needs to be validated as an integer, {date} as a date string, and I cannot just put them under the same path, because then the variable needs to be named something like {dateOrId}, which is super ugly and misleading (but works!).

Given that the methods don't overlap because of different verbs, there's no way this can ever cause a conflict, and it works fine in the real world as well.

Please reconsider this limitation in the future.

[shockey]

@nickdnk interesting point - I see where you're coming from.

Consider opening an issue over at https://github.com/OAI/OpenAPI-Specification - they're the folks in charge of what's allowed in Swagger/OpenAPI documents 😄

[Ashikpaul]

Any updates?

[5-k]

It does weird behavior even if the prefix is different

Semantic error at paths.

/dependency/{project}/{component}/{installation}/{name}
Equivalent paths are not allowed.
Semantic error at paths.

/installation/{project}/{component}/{name}
Equivalent paths are not allowed.

[WahidBitar]

Is there any hope to consider the verb as part of the path uniqueness??
I just wanted to mention this before the end of 2023 ^_^

[Harushii18]

Is there any hope to consider the verb as part of the path uniqueness?? I just wanted to mention this before the end of 2023 ^_^

I would also like to ask about the progress of using the verb for path uniqueness.