SpringDoc OpenAPI 自定义模型解析器与类型名称解析器的正确使用方式

在使用SpringDoc OpenAPI为Spring Boot项目生成API文档时，开发者有时需要自定义模型解析器(ModelResolver)和类型名称解析器(TypeNameResolver)的行为。本文将通过一个典型场景，深入分析如何正确实现这些自定义配置，避免常见的陷阱。

问题背景

在Spring Boot 3.2.4项目中，当开发者尝试通过继承ModelResolver和TypeNameResolver来实现自定义模型名称处理时，可能会遇到一个意外现象：所有包装在ResponseEntity中的响应模型，在生成的OpenAPI文档中会显示完整的ResponseEntity结构，而不仅仅是预期的响应体模型。

核心问题分析

问题的根源在于自定义ModelResolver的实现方式。当直接继承ModelResolver并创建新实例时，实际上覆盖了SpringDoc OpenAPI默认的模型解析逻辑，导致对ResponseEntity等特殊类型的处理方式发生了变化。

正确实现方案

要实现与设置springdoc.use-fqn=true相同的效果，同时保持其他默认行为不变，推荐以下两种方式：

方案一：使用全局配置

最简单的方式是直接设置全局的TypeNameResolver：

@PostConstruct
public void init() {
    TypeNameResolver.std.setUseFqn(true);
}

这种方式简单直接，不需要自定义ModelResolver。

方案二：正确注册自定义解析器

如果需要更复杂的自定义逻辑，可以按照以下方式实现：

@Configuration
public class OpenApiCustomConfiguration {
    
    @Bean
    public ModelResolver modelResolver(ObjectMapper objectMapper) {
        TypeNameResolver resolver = new DefaultTypeNameResolver();
        resolver.setUseFqn(true);
        return new ModelResolver(objectMapper, resolver);
    }
}

关键点在于：

1. 使用DefaultTypeNameResolver而不是直接继承TypeNameResolver
2. 确保自定义ModelResolver被正确注册为Spring Bean

技术原理

SpringDoc OpenAPI内部对ResponseEntity等特殊类型有专门的解析逻辑。当覆盖默认的ModelResolver时，这些特殊处理可能会丢失。正确的做法是：

1. 保持默认的模型解析流程
2. 只修改需要的部分（如类型名称解析策略）
3. 确保自定义组件正确集成到SpringDoc的处理链中

最佳实践建议

1. 优先使用配置属性springdoc.use-fqn实现简单需求
2. 需要复杂自定义时，尽量扩展而不是完全替换默认组件
3. 测试自定义组件对各种返回类型（如ResponseEntity、Page等）的影响
4. 考虑使用@Primary注解确保自定义组件优先于默认组件

通过遵循这些原则，开发者可以灵活定制OpenAPI文档生成行为，同时避免破坏框架的默认处理逻辑。