SpringDoc OpenAPI中@JsonUnwrapped注解与多态转换器的兼容性问题解析

问题背景

在Spring Boot应用中，SpringDoc OpenAPI是一个广泛使用的库，用于自动生成OpenAPI/Swagger文档。近期在升级到SpringDoc OpenAPI 2.6.0版本后，开发者发现了一个与Jackson的@JsonUnwrapped注解相关的兼容性问题。

现象描述

当项目中同时满足以下两个条件时，就会出现问题：

1. 在模型类中使用了@JsonUnwrapped注解
2. 启用了多态转换器(polymorphic-converter)

具体表现为：在生成的OpenAPI Schema中，被@JsonUnwrapped注解标记的属性及其内部属性会完全消失，导致API文档不完整。

技术原理分析

@JsonUnwrapped注解的作用

@JsonUnwrapped是Jackson库提供的一个注解，它允许将一个对象的属性"展开"到其父对象中。例如：

public class RootModel {
    private int rootProperty;
    
    @JsonUnwrapped
    private UnwrappedModel unwrappedModel;
}

public class UnwrappedModel {
    private int unwrappedProperty;
}

在JSON序列化时，上述结构会变成：

{
  "rootProperty": 123,
  "unwrappedProperty": 456
}

而不是：

{
  "rootProperty": 123,
  "unwrappedModel": {
    "unwrappedProperty": 456
  }
}

多态转换器的影响

SpringDoc OpenAPI 2.6.0引入的多态转换器(PolymorphicModelConverter)旨在更好地处理Java中的多态类型。然而，这个转换器在处理带有@JsonUnwrapped注解的类时，会错误地忽略这些展开的属性。

解决方案

目前有两种可行的解决方案：

方案一：禁用多态转换器

在application.properties或application.yml中配置：

springdoc.model-converters.polymorphic-converter.enabled=false

这种方法简单直接，但会失去多态类型处理的功能。

方案二：显式注册父类型

对于包含@JsonUnwrapped注解的类，可以手动将其注册为父类型：

@SpringBootApplication
public class MyApplication {
    public static void main(String[] args) {
        SpringDocUtils.getConfig().addParentType(RootModel.class.getSimpleName());
        SpringApplication.run(MyApplication.class, args);
    }
}

这种方法保留了多态转换器的功能，同时解决了@JsonUnwrapped的问题。

最佳实践建议

1. 如果项目中没有使用多态类型，建议直接禁用多态转换器
2. 如果必须使用多态转换器，则需要对所有包含@JsonUnwrapped注解的类进行显式注册
3. 考虑在项目启动时自动扫描和注册这些类，而不是手动添加

总结

SpringDoc OpenAPI 2.6.0引入的多态转换器虽然增强了多态类型的支持，但与@JsonUnwrapped注解存在兼容性问题。开发者可以根据项目需求选择适合的解决方案。这个问题预计会在未来的版本中得到修复，在此之前，上述解决方案可以保证API文档的正确生成。