SpringDoc OpenAPI 中 JsonNullable 支持方案解析

在实际开发中，我们经常需要区分 API 请求中字段的三种状态：存在且有值、存在但为 null、以及字段不存在。Jackson-databind-nullable 库提供的 JsonNullable 类型正是为解决这个问题而生。本文将深入探讨如何在 SpringDoc OpenAPI 项目中正确集成 JsonNullable 支持。

问题背景

当开发者在 SpringBoot 项目中使用 SpringDoc OpenAPI 生成 API 文档时，如果 DTO 中使用了 JsonNullable 类型，Swagger UI 的展示会出现异常。具体表现为：

1. 本该显示对象属性的地方只显示 "present": true
2. 无法正确识别字段的三种状态（有值/null/未定义）
3. 自动生成的客户端代码无法正确处理字段缺失情况

核心解决方案

1. Jackson 模块注册

首先需要确保 JsonNullableModule 被正确注册到 Jackson ObjectMapper 中：

@Configuration
public class JacksonConfig {
    @Bean
    public Module jsonNullableModule() {
        return new JsonNullableModule();
    }
}

这个模块提供了 JsonNullable 类型的序列化和反序列化逻辑。

2. SpringDoc 模型转换器

为了让 SpringDoc 正确处理 JsonNullable 类型，需要实现自定义的 ModelConverter：

public class JsonNullableModelConverter implements ModelConverter {
    private final ObjectMapper objectMapper;

    public JsonNullableModelConverter(ObjectMapper objectMapper) {
        this.objectMapper = objectMapper;
    }

    @Override
    public Schema resolve(AnnotatedType type, ModelConverterContext context, 
                         Iterator<ModelConverter> chain) {
        JavaType javaType = objectMapper.constructType(type.getType());
        if (JsonNullable.class.isAssignableFrom(javaType.getRawClass())) {
            // 解包 JsonNullable 的内部类型
            return context.resolve(new AnnotatedType()
                .type(javaType.containedType(0))
                .ctxAnnotations(type.getCtxAnnotations()));
        }
        return chain.hasNext() ? chain.next().resolve(type, context, chain) : null;
    }
}

3. DTO 定义规范

使用 JsonNullable 时，DTO 需要遵循特定模式：

@Data
@JsonInclude(JsonInclude.Include.NON_NULL)
public class PatchDTO {
    // 必须初始化为 undefined
    private JsonNullable<String> name = JsonNullable.undefined();
    
    // 其他字段同理
    private JsonNullable<Integer> age = JsonNullable.undefined();
}

高级配置方案

对于需要更精细控制的情况，可以完全接管 SpringDoc 的 ObjectMapper：

@Bean
public ObjectMapperProvider objectMapperProvider(SpringDocConfigProperties properties) {
    ObjectMapperProvider provider = new ObjectMapperProvider(properties);
    provider.jsonMapper().registerModule(new JsonNullableModule());
    return provider;
}

实际应用效果

正确配置后：

1. Swagger UI 会像普通字段一样显示 JsonNullable 包装的类型
2. API 文档能准确反映字段的可空性
3. 生成的客户端代码能正确处理三种字段状态
4. 请求示例会正确显示字段的可选性

最佳实践建议

1. 始终初始化 JsonNullable 字段为 undefined
2. 在 @JsonInclude 注解中使用 NON_NULL 策略
3. 为团队编写明确的 JsonNullable 使用规范
4. 在接口文档中说明字段的三种状态含义
5. 考虑添加全局异常处理，统一处理 JsonNullable 解析错误

通过以上方案，开发者可以在 SpringDoc OpenAPI 项目中完美集成 JsonNullable 支持，实现更精确的 API 字段状态控制，同时保持文档生成的准确性。