SpringDoc忽略@JsonIdentityReference注解：如何将JPA实体关联属性映射为ID列表？

你遇到的这个问题挺常见的——SpringDoc默认不会自动识别Jackson的@JsonIdentityReference注解对序列化结果的修改，所以生成的OpenAPI规范里还是会展示实体类的完整结构，而不是我们期望的ID集合。下面给你几个可行的解决方案，按实现复杂度从简单到进阶排序：

方案一：手动在字段上指定@Schema注解 #

这是最直接的方法，直接在User类的orders字段上用@Schema注解明确指定类型：

@OneToMany(mappedBy = "order")
@JsonIdentityReference(alwaysAsId=true)
// 明确指定数组元素类型为Long（Order的ID类型）
@Schema(type = "array", implementation = Long.class)
private List<Order> orders = Collections.emptyList();

同样的，你也可以给Order类里的user和products字段做类似配置：

@ManyToOne
@JoinColumn(name = "user_id")
@JsonIdentityReference(alwaysAsId=true)
@Schema(implementation = Long.class)
private User user;

这个方法的优点是快速见效，适合小范围调整；缺点是如果有很多关联字段，需要逐个添加注解，有点繁琐。

方案二：自定义SchemaProcessor全局处理 #

如果你的项目里有大量需要转成ID的关联字段，可以写一个全局的Schema处理器，让SpringDoc自动识别带有@JsonIdentityReference(alwaysAsId=true)的字段，把对应的Schema改成ID类型：

import io.swagger.v3.core.converter.AnnotatedType;
import io.swagger.v3.core.converter.ModelConverter;
import io.swagger.v3.core.converter.ModelConverterContext;
import io.swagger.v3.oas.models.media.Schema;
import org.springframework.stereotype.Component;
import com.fasterxml.jackson.annotation.JsonIdentityReference;
import jakarta.persistence.Id;
import java.lang.reflect.Field;
import java.lang.reflect.ParameterizedType;
import java.lang.reflect.Type;
import java.util.Iterator;
import java.util.stream.Stream;

@Component
public class JsonIdentityReferenceConverter implements ModelConverter {

    @Override
    public Schema resolve(AnnotatedType annotatedType, ModelConverterContext context, Iterator<ModelConverter> chain) {
        JsonIdentityReference annotation = annotatedType.getAnnotation(JsonIdentityReference.class);
        if (annotation != null && annotation.alwaysAsId()) {
            Type type = annotatedType.getType();
            // 处理集合类型（比如List<Order>）
            if (type instanceof ParameterizedType paramType) {
                Type entityType = paramType.getActualTypeArguments()[0];
                Class<?> entityClass = (Class<?>) entityType;
                // 获取实体类的@Id字段类型
                Field idField = Stream.of(entityClass.getDeclaredFields())
                        .filter(f -> f.isAnnotationPresent(Id.class))
                        .findFirst()
                        .orElseThrow(() -> new RuntimeException("找不到@Id字段在实体类: " + entityClass.getName()));
                // 构建ID类型的数组Schema
                Schema<?> idSchema = context.resolve(new AnnotatedType(idField.getType())).orElse(null);
                Schema<?> arraySchema = new Schema<>();
                arraySchema.setType("array");
                arraySchema.setItems(idSchema);
                return arraySchema;
            } 
            // 处理单个实体类型（比如User）
            else {
                Class<?> entityClass = (Class<?>) type;
                Field idField = Stream.of(entityClass.getDeclaredFields())
                        .filter(f -> f.isAnnotationPresent(Id.class))
                        .findFirst()
                        .orElseThrow(() -> new RuntimeException("找不到@Id字段在实体类: " + entityClass.getName()));
                return context.resolve(new AnnotatedType(idField.getType())).orElse(null);
            }
        }
        return chain.hasNext() ? chain.next().resolve(annotatedType, context, chain) : null;
    }
}

这个处理器会自动遍历所有带有目标注解的字段，提取关联实体的ID类型，替换原来的Schema。只需要把这个类注册为Spring组件，SpringDoc就会自动使用它。

方案三：升级SpringDoc版本（可选） #

如果你的SpringDoc版本比较旧，建议先升级到最新稳定版（比如v2.x系列），因为新版本对Jackson注解的兼容性更好，有可能已经修复了这个识别问题。你可以在pom.xml（Maven）或者build.gradle（Gradle）里更新依赖：

Maven示例：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version>
</dependency>

Gradle示例：

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'

验证方法 #

配置完成后，启动应用，访问/swagger-ui.html或者/v3/api-docs，查看User模型的orders字段，应该已经显示为array[integer]（对应Long类型），而不是原来的Order对象数组了。

内容的提问来源于stack exchange，提问作者helt