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

未關閉
  • 哪裡不對？
#3,429 1 則留言 1 個 reaction 已指派 0 人 在 GitHub 檢視

維護者通常 1 天內回覆

@wn1331 已經在處理了。

開始於 2026年11月11日。

評估

難度
4/5
預估耗時
3-5 天
新手友好度
30/100
Issue 類型
缺陷
描述清晰度
基本清楚
活躍度
活躍
技術堆疊
java, kotlin, openapi, spring-boot
領域
backend-api-design

研究方向

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.

由索引模型根據 Issue 內容生成。

描述

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.

主要語言
Java
星號
3.7k
分支
605
平均合併
2 天 11 小時
30 天內合併 PR
17

環境準備

這個專案沒有提供開發容器、Dockerfile 或貢獻指南，環境需要你自己搭建：先看它的 README，通用步驟見我們的新手貢獻指南。

從這裡開始

  1. 先讀完整個 Issue，再讀專案的貢獻指南。
  2. 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
  3. Fork 儲存庫，在一個分支上完成修改。
  4. 送出 Pull Request，並在描述裡引用這個 Issue 編號。

springdoc/springdoc-openapi 的其他 Issue

查看 springdoc/springdoc-openapi 的全部 Issue

相似的 Issue

更多 Java Issue

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。