Property-level @Schema(oneOf) makes every other property of the same type lose its subtypes (static TYPES_TO_SKIP)

Đã đóng
  • Có gì không ổn?
#3,398 0 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 9 ngày

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

Đánh giá

Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức phù hợp với người mới
57/100
Loại issue
Lỗi
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
java, openapi, spring-boot
Lĩnh vực
backend-api-design

Hướng nghiên cứu

Start by reading PolymorphicModelConverter and tracing how TYPES_TO_SKIP affects composePolymorphicSchema when properties are resolved. Reproduce the reported case with the supplied Spring Boot example and inspect GET /v3/api-docs. Done means only the property declaring @Schema(oneOf) is narrowed, while the plain properties still include both Circle and Square.

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

Mô tả

An AI coding agent (Claude Code) found this bug while working in our codebase, traced it to PolymorphicModelConverter, reproduced it in a bare Spring Boot app and wrote this issue. The results below come from that app, not from reading the code alone.

Describe the bug

When one property declares @Schema(oneOf = ...) (or allOf), PolymorphicModelConverter adds the simple name of the property's type to the static set TYPES_TO_SKIP. composePolymorphicSchema then gives no subtypes to every later property of that type, in every class, for the rest of the JVM. Such a property is written as {} (abstract parent) or as a oneOf with only the parent (concrete parent).

Issue #2851 asked for the declared types to win on the field that declares them. The skip now also applies to other fields that declare nothing. The result depends on the order in which the schemas are resolved: in our application, removing an unrelated request body from one endpoint emptied a List<FileDTO> property elsewhere in the spec.

To Reproduce

  • springdoc-openapi-starter-webmvc-api 3.2.0 (also 3.1.1), Spring Boot 4.1.2, Java 25, default settings
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "kind")
@JsonSubTypes({ @JsonSubTypes.Type(value = Circle.class, name = "CIRCLE"),
                @JsonSubTypes.Type(value = Square.class, name = "SQUARE") })
public abstract static class Shape {}
public static class Circle extends Shape { public double radius; }
public static class Square extends Shape { public double side; }

public static class NarrowedHolder {
    @Schema(oneOf = Circle.class)
    public Shape shape;
}
public static class PlainHolder {
    public Shape shape;
}
public static class Outer {
    public NarrowedHolder first;
    public PlainHolder second;
}

@RestController
public static class OuterController {
    @PostMapping("/outer")
    public void outer(@RequestBody Outer body) {}
}

GET /v3/api-docs, then components.schemas:

  • NarrowedHolder.shape: {"oneOf":[{"$ref":"#/components/schemas/Circle"}]} (correct)
  • PlainHolder.shape: {}

With only @PostMapping("/plain") void plain(@RequestBody PlainHolder body), PlainHolder.shape is {"oneOf":[Circle, Square]}.

The same happens inside one class:

public static class BothHolder {
    @Schema(oneOf = Circle.class)
    public Shape narrowed;
    public Shape plain;     // written as {}
}

Expected behavior

PlainHolder.shape and BothHolder.plain are oneOf Circle and Square. Only the property that declares oneOf gets the declared subtypes.

Cause

TYPES_TO_SKIP is static, keyed on the simple class name, and never cleared. The decision should belong to the property that is resolved. Note that in OpenAPI 3.1 mode swagger-core removes @Schema from the ctxAnnotations of a property (SiblingAnnotationFilter), so the converter cannot read it there. We work around it in our project: while the converter resolves a type, it keeps the names of that type's properties that declare oneOf/allOf, and it checks AnnotatedType#getPropertyName() against them when it resolves a property of that type.

Ngôn ngữ chính
Java
Star
3.7k
Fork
605
Merge trung bình
9 ngày 11 giờ
Pull request đã merge (30 ngày)
14

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

Dự án này không cung cấp dev container, Dockerfile hay hướng dẫn đóng góp, nên bạn cần tự thiết lập môi trường: hãy bắt đầu từ README và xem hướng dẫn đóng góp lần đầu của chúng tôi để biết các bước chung.

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 springdoc/springdoc-openapi

Tất cả issue của springdoc/springdoc-openapi

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.