Swagger doesn't allow equivalent rest paths but with different type of parameters

[bssergy]

Guys, I am using node with express for build my api. It gives pretty feature for create the same path with different parameter types:

app.get('/:id(\\d+)/', function (req, res) {
  // req.params.id is now defined here for you
});

app.get('/:ordinal(previous | last)/', function (req, res){
  // req.params.ordinal should be 'previous' or 'last'
});

Unfortunately, swagger doesn't allow use this pretty feature and crashes with error:
API path (or equivalent) already defined

[webron]

In a way, you can express this with OpenAPI. The parameter itself would be a string and you can use a regex to specify the options. Ugly, but doable.

[darrelmiller]

There are plenty of these scenarios that don't even have an ugly option in OpenAPI. e.g.

/restaurantsNear?postalCode={postalCode}
/restaurantsNear?lat={lat}&long={long}

The only way to do this with OpenAPI is

/restaurantsNear{?lat,long,postalCode}

The is problematic because there is no way of expressing that the query parameters must be either PostalCode or Lat and Long. All parameters have to be described as optional which is not accurate.

[dilipkrish]

FWIW, I have a fork of swagger-ui, that supports RFC-6570. So, Its definitely possible to incorporate RFC-6750 support with a little effort. Here is an example of the petstore with templated paths.

Granted that swagger-ui isn't the only spec client, and there are some edge-cases (non-standard or language/stack specific accommodations e.g. matrix parameters or array parameters), but I'd definitely like to see #291 incorporated into the spec.

[webron]

Parent: #574

[gmcelhanon]

We also were using this with the Swagger 1.2 specification to provide explicit semantics around access to resources using the following query patterns:

• /academicWeeks - GetAll (no filter criteria, multiple results)
• /academicWeeks/a3fec78..d1af93 - GetById (surrogate id, single result)
• /academicWeeks?schoolId=123456&weekIdentifier=ABCDEFG - GetByKey (natural key values, single result)
• /academicWeeks?endDate=2016-07-22 - GetByExample (open criteria, multiple results)

The inability to express these semantics after Swagger 1.2 in the generated API client results in a great loss of clarity. Now callers will have to know out-of-band what properties to supply for the natural key of a particular resource, and they will always be getting back an array -- implying there could be multiple results when in fact they really should either get a single result or a 404 response.

[webron]

@gmcelhanon - that wasn't legal in 1.2 either. The tools may puke less by it, but it's not officially supported.

[gmcelhanon]

Just went back and looked at the 1.2 spec again and noticed this line in 5.2.3:

In the operations array, there MUST be only one Operation Object per method.

Breaking this never caused us any trouble with SwaggerUI or the SDK code generation, and it met our needs for more precise semantics around the use of natural keys perfectly. Our world isn't ruled by surrogate ids that we define, and retrieving a resource using the natural key values is a distinctly different "operation" than querying it with general query string parameters.

[webron]

Right, and this may change in the next version. FYI, we changed the structure of the spec in 2.0 to make it more difficult to 'break' such as your experience. While the spec didn't allow it, it was easier to write something that was invalid.

[fehguy]

See merged support for allOf, oneOf, etc. This should address your concerns.