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

Đang mở
  • Có gì không ổn?
#25,477 2 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
35/100
Loại issue
Tính năng
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
java, openapi
Lĩnh vực
backend-api-design, tooling

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.

Ngôn ngữ chính
Java
Star
26.9k
Fork
7.8k
Merge trung bình
2 ngày 10 giờ
Pull request đã merge (30 ngày)
180

Chuẩn bị môi trường

Mở trong Codespaces

Khởi chạy dev container của dự án ngay trên trình duyệt, bằng tài khoản GitHub của bạn.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của OpenAPITools/openapi-generator

Tất cả issue của OpenAPITools/openapi-generator

Issue tương tự

Thêm issue về Java

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.