Spring Data REST: non-exported association schemas renamed to <Name>Response since 3.1.1 (breaking), applied inconsistently

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

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

@wn1331 đang làm issue này rồi.

Từ ngày 11/11/2026.

Đá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
30/100
Loại issue
Lỗi
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
java, kotlin, openapi, spring-boot
Lĩnh vực
backend-api-design

Hướng nghiên cứu

Start with SpringDocDataRestUtils.updateResponseSchemaProperty and the entityInoMap lookup keyed by getSimpleName(), as introduced by PR #3334. Reproduce with an entity that has a non-exported repository, comparing a Set association, a nullable single association, and a non-null single association in the generated /v3/api-docs. Done means the naming rule is consistent across those shapes and @Schema(name) is honoured, which first requires agreeing on the intended behaviour with maintainers.

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

Mô tả

Describe the bug

After upgrading springdoc-openapi-starter-webmvc-ui from 3.0.2 to 3.1.1 (still present in 3.2.0), component schemas for entities that are not exported repositories are renamed. For example, CustomerRelationship becomes CustomerRelationshipResponse in the generated spec. This changes generated client type names in a minor release.

This comes from #3334 (fix for #3136), which makes SpringDocDataRestUtils.updateResponseSchemaProperty rewrite such association properties to a <Name>Response copy. The filtering itself makes sense, but the side effects are surprising:

  1. Breaking rename in a minor version. Nothing in #3334 or the release notes mentions that schema names change.

  2. Inconsistent behaviour. Only two property shapes are rewritten: a direct $ref and items (collections).

    • Set<CustomerRelationship> is rewritten, so the spec contains CustomerRelationshipResponse.
    • A nullable single association (var region: CustomerRegion?) is emitted in OpenAPI 3.1 as oneOf: [{$ref: CustomerRegion}, {type: null}]. It is skipped, so the plain CustomerRegion stays.
    • A non-null single association (CustomerRegion) is rewritten to CustomerRegionResponse.

    Similar relations therefore get different names depending on cardinality and nullability.

  3. @Schema(name) is only honoured if it differs from the class name. entityInoMap is keyed by domainType.getSimpleName() and looked up with the schema name. @Schema(name = "CustomerRelationship") on CustomerRelationship is ignored and the suffix is still added. @Schema(name = "Foo") works because the lookup misses and no copy is created.

To Reproduce
  • Spring Boot 4.x, spring-boot-starter-data-rest, springdoc 3.1.1 or 3.2.0, OpenAPI 3.1.
  • Entity Customer with: 
    @OneToMany(fetch = FetchType.LAZY) var relationships: Set<CustomerRelationship> = emptySet()
@ManyToOne(fetch = FetchType.LAZY) var region: CustomerRegion? = null
    CustomerRelationship and CustomerRegion are entities with no exported repository.
  • Compare /v3/api-docs on 3.0.2 and 3.1.1:
    • 3.0.2: #/components/schemas/CustomerRelationship
    • 3.1.1+: #/components/schemas/CustomerRelationshipResponse; region still references CustomerRegion.
Expected behavior
  • Schema names stay stable across a minor upgrade, or the change is documented as breaking.
  • Handling is consistent for collections, nullable singles (oneOf/allOf wrappers), and non-null singles.
  • An explicit @Schema(name = …) is respected even when it equals the class name, or the suffix is configurable (for example a property to disable the rename).
Workaround

Customize the generated schemas yourself to rename or strip the suffix, or use a @Schema(name) that differs from the class name.

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

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.