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

Abierto
  • ¿Algo no está bien?
#3,429 1 comentario 1 reacción 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

@wn1331 ya está trabajando en esto.

Desde el 11/11/2026.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
30/100
Tipo de issue
Error
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
java, kotlin, openapi, spring-boot
Área
backend-api-design

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
Java
Estrellas
3.7k
Forks
605
Merge medio
2 d 11 h
PR fusionados (30 d)
17

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de springdoc/springdoc-openapi

Todos los issues de springdoc/springdoc-openapi

Issues similares

Más issues de Java

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.