Hacktoberfest 2026：維護者為十月標記出來的 issue，仍然開放、適合新手。 瀏覽 Hacktoberfest issue

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

未關閉
  • 哪裡不對？
#5,366 12 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視

維護者通常 1 天內回覆

還沒有人認領這個 Issue。

評估

難度
5/5
預估耗時
一週以上
新手友好度
25/100
Issue 類型
功能
描述清晰度
需要釐清
活躍度
冷清
技術堆疊
openapi
領域
api, documentation

研究方向

先從本文中連結的 issue 留言中的修訂提案開始，然後檢視目前對 in: querystring 的限制，以及此處描述的 type: apiKey, in: query 互動。完成的標準是：討論中有一個明確且取得共識的規範性提案，或者如果其範圍遭到否決，則重新提交或關閉該 issue。

由索引模型根據 Issue 內容生成。

描述

param serialization

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)

主要語言
Markdown
星號
31.2k
分支
9.2k
平均合併
2 天 9 小時
30 天內合併 PR
17

環境準備

從這裡開始

  1. 先讀完整個 Issue，再讀專案的貢獻指南。
  2. 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
  3. Fork 儲存庫，在一個分支上完成修改。
  4. 送出 Pull Request，並在描述裡引用這個 Issue 編號。

OAI/OpenAPI-Specification 的其他 Issue

查看 OAI/OpenAPI-Specification 的全部 Issue

相似的 Issue

更多 Backend & API Design Issue

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。