Proposal: Querystring in Path Specification

Issue

In some APIs, different query string values specifies the operation done on the resource, thus, result in dramatically different response types and/or parameter requirements. In the case of Foursquare Venues Search API, depending on the intent query string value, the requirement specs of other query string vary.
Such distinction deserves a separate path entity, to allow different descriptions, parameter requirements, responses, etc.

Current State

Currently due to Swagger Spec, on swagger-ui, the generated url for testing is incorrect if a query string is included in the path.

"paths": {
    "/bluelights?query=nearby": {

becomes: .../bluelights?query=nearby?more=...

Proposal

Allow Query Strings in the path key

The example above is allowed. so for example, depending on the path key, "/bluelights?query=nearby" and "/bluelights" are considered separate path entities.

[zdila]

+1

In our case we need it for POST to execute 4 various security actions:

• /v1/security/credentials?action=changePassword
• /v1/security/credentials?action=requestPasswordReset
• /v1/security/credentials?action=resetPassword
• /v1/security/credentials?action=remindUsername

Every action is implemented as different method with different POST body.

We don’t want to distinguish actions by path (eg. /v1/security/credentials/changePassword) because paths should be nouns, not verbs.

[darrelmiller]

@davidnewcomb I agree that using only the path to identify the resource is a nice simplification that is sufficient for most cases. However, a significant number of people come to OpenAPI to try and document an existing API. We have to balance encouraging good practices with being compatible with the wide range of ways HTTP APIs are implemented.