SpringDoc OpenAPI中UpperSnakeCase策略与ParameterObject的兼容性问题解析

问题背景

在Spring Boot应用开发中，开发者经常使用SpringDoc OpenAPI来自动生成API文档。近期发现一个特定场景下的兼容性问题：当DTO类使用@JsonNaming(PropertyNamingStrategies.UpperSnakeCaseStrategy.class)注解配合@ParameterObject时，参数名称转换功能无法正常工作。

问题现象

开发者定义了一个请求DTO类，使用了UpperSnakeCase命名策略：

@JsonNaming(PropertyNamingStrategies.UpperSnakeCaseStrategy.class)
@Data
public class RequestDto {
    private String personalNumber;
    // 其他字段...
}

然后在控制器中使用@ParameterObject注解：

@GetMapping
public Response getData(@ParameterObject @NonNull RequestDto requestDto) {
    return service.getdata(requestDto);
}

期望生成的OpenAPI文档中参数名应为PERSONAL_NUMBER，但实际上仍然保持为personalNumber，不符合UpperSnakeCase的命名规范。

技术分析

这个问题源于SpringDoc OpenAPI对参数名称处理的一个遗漏。虽然Jackson的@JsonNaming注解能够正确序列化/反序列化JSON数据，但在生成OpenAPI文档时，SpringDoc没有完全考虑这种命名策略转换。

深层原因

1. 参数名称处理流程：SpringDoc在处理@ParameterObject时，直接从方法参数获取名称，没有经过Jackson命名策略转换
2. 命名策略应用范围：Jackson的命名策略主要作用于JSON序列化/反序列化过程，而OpenAPI文档生成是独立的过程
3. 反射机制限制：SpringDoc通过反射获取参数信息时，没有访问命名策略转换后的结果

解决方案

临时解决方案

可以通过自定义DelegatingMethodParameterCustomizer来手动实现命名策略转换：

public class MyMethodParameterCustomizer implements DelegatingMethodParameterCustomizer {
    @Override
    public void customize(MethodParameter originalParameter, MethodParameter methodParameter) {
        if (AnnotatedElementUtils.isAnnotated(methodParameter.getContainingClass(), JsonNaming.class)) {
            JsonNaming jsonNaming = methodParameter.getContainingClass().getAnnotation(JsonNaming.class);
            if (jsonNaming.value().equals(PropertyNamingStrategies.UpperSnakeCaseStrategy.class)) {
                try {
                    Field parameterNameField = FieldUtils.getDeclaredField(
                        methodParameter.getClass(), "parameterName", true);
                    parameterNameField.set(methodParameter,
                        PropertyNamingStrategies.UpperSnakeCaseStrategy.INSTANCE.translate(
                            methodParameter.getParameterName()));
                } catch (IllegalAccessException e) {
                    // 处理异常
                }
            }
        }
    }
}

然后注册为Spring Bean：

@Bean
DelegatingMethodParameterCustomizer delegatingMethodParameterCustomizer() {
    return new MyMethodParameterCustomizer();
}

注意事项

1. 反射风险：此方案使用了反射修改私有字段，可能存在兼容性问题
2. 维护成本：这是一个临时解决方案，需要关注SpringDoc的后续版本更新
3. 测试验证：需要全面测试确保不影响其他功能

最佳实践建议

1. 命名一致性：考虑在项目早期确定统一的命名规范，避免混合使用不同命名策略
2. 文档注释：对于使用特殊命名策略的DTO类，添加详细注释说明预期行为
3. 版本跟踪：关注SpringDoc OpenAPI的版本更新，及时升级获取官方修复

总结

SpringDoc OpenAPI与Jackson命名策略的集成在某些特定场景下存在不足，特别是UpperSnakeCase策略与ParameterObject的组合使用。虽然可以通过自定义组件临时解决问题，但长期来看，建议等待官方修复或考虑调整项目命名规范以避免此类问题。开发者在使用高级特性时应当充分测试，确保各组件间的兼容性。