How to handle ambiguous paths in the API spec

[iuliag]

Overview

How to handle ambiguous paths in the API spec?

As seen in the docs linting warnings when running npm run docs, we have some ambiguous/conflicting paths.
Example:

Paths should resolve unambiguously. Found two ambiguous paths: `/sites/by-delivery-type/{deliveryType}` and `/sites/{siteId}/experiments`.

In some cases, it's clear that the static path segments like by-delivery-type,experiements etc. don't match with the format requirements of the path parameters like siteId (uuid), deliveryType (enum).

But it's still confusing and error prone, as routes have to be ordered top down from the most specific to the more dynamic in the API implementation, in order to have the proper behavior of the API implemented.

Details

OpenAPI spec v3.1.1 https://spec.openapis.org/oas/v3.1.1.html#patterned-fields mentions:

4.8.8.1 Patterned Fields

Field Pattern	Type	Description
/{path}	Path Item Object	A relative path to an individual endpoint. The field name MUST begin with a forward slash (/). The path is appended (no relative URL resolution) to the expanded URL from the Server Object’s url field in order to construct the full URL. Path templating is allowed. 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. In case of ambiguous matching, it’s up to the tooling to decide which one to use.

4.8.8.2 Path Templating Matching
Assuming the following paths, the concrete definition, /pets/mine, will be matched first if used:

/pets/{petId}
/pets/mine

The following paths are considered identical and invalid:

/pets/{petId}
/pets/{name}

The following may lead to ambiguous resolution:

/{entity}/me
/books/{id}

Proposed Actions

Come up with a recommendation so that we can avoid ambiguous paths in the future from the API design phase.

[iuliag]

cc: @solaris007, @chicharr