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 摘要。