Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

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

Aberta
  • Algo errado?
#5,366 12 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
5/5
Tempo estimado
Mais de uma semana
Facilidade para iniciantes
25/100
Tipo de issue
Funcionalidade
Clareza
Precisa de esclarecimento
Status de atividade
Pouca atividade
Stack de tecnologia
openapi
Domínio
api, documentation

Direção de pesquisa

Comece pela proposta revisada no comentário da issue vinculado no corpo e, em seguida, revise as restrições atuais de in: querystring e a interação de type: apiKey, in: query descrita aqui. Considera-se concluído quando a discussão tiver uma proposta normativa clara e acordada, ou quando a issue for reaberta ou fechada se o escopo for rejeitado.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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)

Linguagem predominante
Markdown
Estrelas
31.2k
Forks
9.2k
Merge médio
2d 9h
PRs com merge (30d)
17

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de OAI/OpenAPI-Specification

Todas as issues de OAI/OpenAPI-Specification

Issues semelhantes

Mais issues de Backend & API Design

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.