为何部分$ref缺失#/components/schemas/前缀？SpringDoc生成异常

当实体类添加@JsonIdentityInfo注解后，Jackson会为该类生成特殊序列化规则以处理循环引用或重复对象标识。springdoc在解析这类类的Schema时，内部逻辑错误地将Jackson生成的对象ID引用直接作为$ref的值，未加上OpenAPI规范要求的#/components/schemas/前缀，导致生成的引用不符合规范。

解决方案1：自定义SchemaProcessor修复$ref前缀 #

创建自定义SchemaProcessor，在Schema生成后检查并补全缺失的前缀：

import io.swagger.v3.core.converter.AnnotatedType;
import io.swagger.v3.core.converter.ModelConverterContext;
import io.swagger.v3.oas.models.media.Schema;
import org.springdoc.core.processor.SchemaProcessor;
import org.springframework.stereotype.Component;

import java.util.Map;

@Component
public class RefFixSchemaProcessor implements SchemaProcessor {

    @Override
    public void process(Schema<?> schema, ModelConverterContext context, AnnotatedType type) {
        // 修复当前schema的$ref
        if (schema.get$ref() != null && !schema.get$ref().startsWith("#/components/schemas/")) {
            schema.set$ref("#/components/schemas/" + schema.get$ref());
        }
        // 递归修复嵌套属性的schema
        if (schema.getProperties() != null) {
            for (Map.Entry<String, Schema<?>> entry : schema.getProperties().entrySet()) {
                process(entry.getValue(), context, type);
            }
        }
        // 修复数组项的schema
        if (schema.getItems() != null) {
            process(schema.getItems(), context, type);
        }
    }
}

解决方案2：配置springdoc忽略Jackson身份标识注解 #

在application.properties或application.yml中添加配置，让springdoc跳过@JsonIdentityInfo的影响：

springdoc.model-converter-jackson.ignore-json-identity-info=true

该配置会让springdoc解析Schema时忽略Jackson的身份标识逻辑，直接生成符合规范的Schema引用。

解决方案3：替换@JsonIdentityInfo处理循环引用 #

若仅需处理循环引用场景，可改用Jackson的@JsonManagedReference和@JsonBackReference组合替代@JsonIdentityInfo，既解决循环引用问题，又不干扰OpenAPI Schema生成：

// 父实体类
public class Parent {
    @JsonManagedReference
    private List<Child> children;
    // 其他字段、getter/setter
}

// 子实体类
public class Child {
    @JsonBackReference
    private Parent parent;
    // 其他字段、getter/setter
}

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