Hacktoberfest 2026: die Issues, die Maintainer für den Oktober markiert haben – offen und einsteigerfreundlich. Hacktoberfest-Issues durchsuchen

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

Offen
  • Stimmt etwas nicht?
#5,366 12 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Anfängerfreundlichkeit
25/100
Issue-Typ
Feature
Klarheit
Muss geklärt werden
Aktivitätsstatus
Ruhig
Tech-Stack
openapi
Bereich
api, documentation

Rechercherichtung

Beginne mit dem überarbeiteten Vorschlag im aus dem Beschreibungstext verlinkten Issue-Kommentar und prüfe dann die aktuellen Einschränkungen für in: querystring sowie die hier beschriebene Interaktion von type: apiKey, in: query. Als erledigt gilt die Aufgabe, wenn die Diskussion einen klaren, einvernehmlich angenommenen normativen Vorschlag enthält oder das Issue neu eingereicht oder geschlossen wird, falls sein Umfang abgelehnt wird.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

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)

Vorherrschende Sprache
Markdown
Sterne
31.2k
Forks
9.2k
Ø Merge
2 T. 9 Std.
Gemergte PRs (30 T.)
17

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus OAI/OpenAPI-Specification

Alle Issues in OAI/OpenAPI-Specification

Ähnliche Issues

Weitere Issues zu Backend & API Design

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.