[REQ] Parse OpenAPI 3.2 documents (query / additionalOperations / in: querystring) with the released swagger-parser via an adapter

Offen
  • Stimmt etwas nicht?
#25,477 2 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
35/100
Issue-Typ
Feature
Klarheit
Größtenteils klar
Aktivitätsstatus
Aktiv
Tech-Stack
java, openapi
Bereich
backend-api-design, tooling

Rechercherichtung

Start at CodegenConfigurator.toContext() and read the existing parser call and the Oas31RawSpecRecovery precedent. Check how MergedSpecBuilder consumes parsed specs, then verify parser behavior for a minimal OpenAPI 3.2 document rewritten to 3.1, including relative $refs. Done means the generate path preserves the named 3.2 members and provides a tested way for generation to access restored operations.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

Is your feature request related to a problem? Please describe.

openapi-generator can't read OpenAPI 3.2 documents today. With the released swagger-parser (2.1.48), OpenAPIParser.readLocation returns no OpenAPI object for a minimal document with openapi: 3.2.0. It then tries the Swagger 2 converter and reports:

attribute paths.'/things'.query is unexpected
attribute paths.'/things'.additionalOperations is unexpected
attribute openapi is unexpected
attribute swagger is missing

in: querystring is not reported at all.

I opened the upstream PRs for 3.2 support: swagger-api/swagger-core#5326, swagger-api/swagger-parser#2401 and swagger-api/swagger-parser#2402. They are still open, and swagger-core 3.0.0 (released 2026-10-28) doesn't include them. I'm not aware of an announced release date. #24982 (codegen for query, additionalOperations and in: querystring) is blocked on them.

Describe the solution you'd like

An adapter in front of the parser call used by the generate workflow, i.e. CodegenConfigurator.toContext(), which the CLI and the Maven/Gradle plugins go through. This is also where the TODO for #844 ("custom spec loader implementations") sits.

  • Default: for 3.0/3.1 documents, call readLocation exactly as today.

  • 3.2 documents (root openapi: 3.2.x):

    1. The adapter reads the raw text itself and rewrites it:
      • openapi becomes 3.1.0;
      • query and additionalOperations on path items move into x-oas32-* extensions;
      • in: querystring becomes in: query, with the original value kept in x-oas32-in. The 3.1 path rejects querystring as an in value.
      • Every other 3.2-only key in a fixed table also moves into x-oas32-*, e.g. $self, tag parent/kind, response summary, itemSchema, oauth2MetadataUrl, deviceAuthorization. Otherwise the 3.1 path reports them as unexpected attributes, and generation fails under the default validateSpec. They are kept rather than silently dropped.
    2. It parses the result with OpenAPIV3Parser.readContents(text, auth, options, inputSpec), so relative $refs still resolve against the original location.
    3. It deserializes the moved query/additionalOperations maps into Operation objects and keeps them on PathItem extensions under fixed keys. The released swagger-models has no PathItem.query/additionalOperations and no SpecVersion.V32. A small accessor (e.g. Oas32.query(pathItem)) is the only thing DefaultGenerator and #24982 would read. #24982 would switch to that accessor instead of the new model getters.

    When swagger-core/swagger-parser ship 3.2 support, the rewrite and the accessor are the two places that change.

There is precedent for re-reading the raw document and carrying facts in x- extensions: Oas31RawSpecRecovery (#24760).

With swagger-parser 2.1.48 (resolve=true), a minimal 3.2 document rewritten as in step 1 parsed as 3.1 with no messages. The moved members came back as raw extension values: maps on the path item, x-oas32-in on the parameter. Turning those maps into Operation objects and generating from them is not verified yet.

Scope and open points:

  • The first scope is those three members, not full 3.2 support.
  • The first PR would only wire the generate path and MergedSpecBuilder. The other parse sites call OpenAPIParser directly: validate in CLI/Maven/Gradle/Mill, the Maven plugin's spec-hash and collapsedSpec helpers, the online service, and Oas31RawSpecRecovery. I'd make the adapter a reusable helper so they can switch to it later.
  • $refs to external files that themselves use 3.2-only members would need the same rewrite.
  • $refs inside restored operations don't go through the parser's resolver. This needs dedicated tests.
  • Generated clients that parse the spec at runtime (java okhttp-gson dynamicOperations) aren't covered. They stay limited to their own pinned parser.
Describe alternatives you've considered
  • Wait for the swagger-core/swagger-parser releases. Cleanest, but there's no date.
  • Depend on a fork of the parser and models published under another groupId. It uses the same io.swagger.v3 packages, so it would clash with the official artifacts on users' classpaths unless excluded or shaded. It also means relying on an individually maintained artifact for the core parser.
  • Patch swagger-parser classes at runtime (bytecode instrumentation). Fragile across parser versions, and it adds deployment requirements for CLI, plugin and embedded use.
Additional context

Decisions I'd need before starting:

  1. Is rewriting a 3.2 document to 3.1 at the generate entry point acceptable?
  2. Are extension-held Operations plus an accessor acceptable until swagger-core ships the model fields?
  3. For other 3.2-only keys under validateSpec, is "move to x-oas32-* and keep" the right policy, or should they produce a warning or error?

If this works for you, I'd open a PR with the adapter and tests first, then rebase #24982 onto it. If you'd rather wait for the upstream releases, I'll keep #24982 as a draft until then.

Vorherrschende Sprache
Java
Sterne
26.9k
Forks
7.8k
Ø Merge
2 T. 10 Std.
Gemergte PRs (30 T.)
180

Entwicklungsumgebung

In Codespaces öffnen

Startet den Dev-Container des Projekts im Browser, mit Ihrem eigenen GitHub-Konto.

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 OpenAPITools/openapi-generator

Alle Issues in OpenAPITools/openapi-generator

Ähnliche Issues

Weitere Issues zu Java

Neue Issues direkt in Ihr Postfach

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