Accommodate legacy APIs by allowing query parameters in the path

Issue by @earth2marsh

---

There are real APIs where a query string may determine the structure of the response, for example verbose=true, metadata=1, action=reboot.

However, Those cannot be expressed in Swagger 2.0 today because the path/verb maps onto a response model 1:1.

While it may be a bit of a kludge, consider a unique path where the query string is hard-wired into the path: "path":"/me?metadata=1"

The order of the query params may not be determined in real situations, but for the purpose of defining methods in the spec, this may be an acceptable compromise to accommodate legacy services.

[webron]

Comment by @maxlinc

---

@BSalita you’d need to write another specification just for how the conditionals are processed.

I still think the answer to those sorts of problems is still RFC 6570, because it’s the closest thing to that specification.

At this point I think we should just ask tools to handle “path” as “the path portion of a URI template”, and to consider an “x-query” extension for the “query portion of a URI template”. I think it’s better to have projects like swagger-js get started with basic URI template support before we try to extend it to cover query.

If they decide it isn’t difficult to support it, here’s how I’d expect it to work:

The default:

path: "/me?metadata=1"
# x-query: "{?parameters*}"

would produce: http://example.com/me?metadata=1?foo=oof&bar=rab&baz=zab, which has the problem @fehguy mentioned.

A simple override tells the tool how you want it handled:

path: "/me?metadata=1"
x-query: "{&parameters*}" # changed the prefix to &

That produces http://example.com/me?metadata=1&foo=oof&bar=rab&baz=zab, which is correct.

Even more complex patterns are possible, for example:

path: "/me?metadata=1"
x-query: "{&foo,bar}{;baz}"

Produces http://example.com/me?metadata=1&foo=oof&bar=rab;baz=zab.

The only thing I don’t like about this is that path is a misnomer now. route would be a more appropriate name if it can include (some of) the query.

[antrix190]

Hey @webron I have something similar use case to handle, do we have a solution/work around to this issue yet?