v3.3: Allow `in: query` and `in: querystring` and/or multiple `in: querystring`s together?

本文からリンクされている issue コメントの改訂された提案から始め、その後、ここで説明されている現在の in: querystring の制限と type: apiKey, in: query の相互作用を確認します。完了とは、議論に明確で合意された規範的な提案が1つある状態、またはスコープが却下された場合に issue を再登録するかクローズすることです。

IMPORTANT NOTE: @karenetheridge has convinced me that in: querystring and in: query really cannot be combined, so this original post here is not really accurate anymore. However,in: querystring overrides might work. I'll try to clean this all up or maybe re-file it when I get a chance.

Revised proposal starts at https://github.com/OAI/OpenAPI-Specification/issues/5366#issuecomment-4672179041

NOTE: This is primarily relevant if #5320 is accepted, as it dramatically widens the scope of potential interactions by allowing global parameters. If #5320 is rejected, this can probably just be closed wontfix.

To keep things simple with in: querystring, we added two restrictions, which apply across both the Operation and Path Item level:

• There can only be one in: querystring parameter
• If there is an in: querystring parameter, there cannot be any in: query parameters

We missed a querystring option elsewhere

However, we did overlook that the type: apiKey, in: query Security Scheme effectively adds an in: query parameter which we did not explicitly forbid (and I do not consider the current wording to implicitly forbid it, as "parameter" was intended to mean Parameter Object).

Technically, there isn't a problem here: You can just tack the API key parameter onto the query string on either end, and as long as you remove it first when parsing, there's no ambiguity.

None of the potential problems are new

• Ambiguous groups of object-property-name-defined query paramters already occur with in: query, explode: true
• As noted (and warned against) in Appendix E, with very particular use of allowReserved: true with minimal percent-encoding (and no form-urlencoded-specific escaping), plus use of a form-urlencoded parser, it is possible to misinterpret a + as an escaped space when it was serialized as a literal +. This requires the user to make an effort to work around the typical behavior, and we already warn that it will cause a bug if the user does so.

We can make the ambiguity better, and the escaping/encoding issue is not worse

We could also improve the situation with in: querystring by mandating its position relative to other query parameters (whether in: querystring or in: query). For example:

• when multiple in: querystring paramters are present, the global ones MUST be serialized first (directly after the ?), in the order they appear in the global array, then the path item ones, then the operation ones
• when in: querystring paramters are present, they MUST all appear before any in: query or security scheme parameters (or MUST all appear after, it doesn't matter as long as it is consistent)

This would substantially reduce the number of possible ways to parse the resulting URL when it is recieved.

We could also make corresponding SHOULD recommendations regarding in: query (and other) parameter ordering, we just can't make it a MUST because of compatibility. In fact, without this SHOULD, the behavior is already inherently implementation-defined.

(paging @karenetheridge for implementor feedback)