Paths are equivalent

Issue ID: v3-semantic-path-equivalent

Description

Your API contains paths that are equivalent. In practice, these paths are considered to be identical because there is no way of telling them apart.

This can happen, for example, if you have defined same path but with different parameter name for different operations. The parameter name alone does not make the path unique.

The OpenAPI Specification (OAS) states that all paths must be unique.

For more details, see the OpenAPI Specification.

Example

The following is an example of how this issue could look in your API definition. GET and PUT operations have the same path but different parameter:

{
    "paths":{  
        "/path/{IDs}":{
            "get": {
                "description": "Get the ID list",
                "parameters": {
                    "name": "IDs",
                    "in": "path",
                    "required": true,
                    "type": "string"
                    // ...
                }
            }
        },
        "/path/{addIDs}": {
            "put": {
                "description": "Add IDs to the ID list",
                "parameters": {
                    "name": "addIDs",
                    "in": "path",
                    "required": true,
                    "type": "string"
                    // ...
                }
            }
        }
    }
}

Remediation

Define a single path /path/{parameter} with multiple operations (here GET and PUT):

{
    "/path/{IDs}": {
        "get": {
            "description": "Get the ID list",
            "parameters": {
                "name": "IDs",
                "in": "path",
                "required": true,
                "type": "string"
                // ...
            }
        },
        "put": {
            "description": "Add IDs to the ID list",
            "parameters": {
                "name": "addIDs",
                "in": "path",
                "required": true,
                "type": "string"
                // ...
            }
        }
    }
}

If you need multiple paths, make sure that all paths are considered unique.