Springfox Swagger与Spring Boot2无法正确解析嵌套泛型问题

问题原因 #

1. Java类型擦除机制：泛型的实际参数类型在编译后会被擦除，Springfox 3.0.0默认的类型解析逻辑无法自动识别TestResp<T>中T的具体实现类TestData，因此将data字段默认解析为object。
2. 控制器方法权限错误：你的testResp()方法被定义为private，Spring MVC无法将私有方法识别为请求处理方法，这会导致接口无法正常访问，同时干扰Swagger对接口元数据的正确扫描。

解决方法 #

方法一：创建泛型子类（最简方案） #

通过创建明确指定泛型参数的子类，让Springfox直接识别具体类型：

// 新增具体响应子类
@Data
public class TestDataResp extends TestResp<TestData> {}

修改控制器方法，修正权限为public并返回该子类：

@RestController
public class TestController {

    @GetMapping("test")
    @ApiOperation("test")
    public TestDataResp testResp() {
        TestDataResp resp = new TestDataResp();
        resp.setData(new TestData("test"));
        return resp;
    }
}

方法二：通过Swagger注解指定泛型类型 #

无需创建子类，直接通过注解明确泛型的实际类型：

先给泛型包装类添加@ApiModel注解：

@Data
@ApiModel(value = "TestResp", description = "通用响应包装类")
public class TestResp<T> {
    @ApiModelProperty(value = "响应数据")
    private T data;
}

然后在控制器方法中，通过@ApiResponse指定泛型的具体实现：

@RestController
public class TestController {

    @GetMapping("test")
    @ApiOperation("test")
    @ApiResponse(responseCode = "200", description = "成功响应",
        content = @Content(schema = @Schema(implementation = TestResp.class,
            subTypes = {TestData.class})))
    public TestResp<TestData> testResp() {
        return new TestResp<>(new TestData("test"));
    }
}

方法三：全局配置类型解析器 #

如果项目中有大量泛型接口需要处理，可通过Docket配置全局注册泛型类型：

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        TypeResolver typeResolver = new TypeResolver();
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.basePackage("你的控制器包路径"))
                .paths(PathSelectors.any())
                .build()
                .additionalModels(typeResolver.resolve(TestResp.class, TestData.class));
    }
}

验证 #

修改完成后重启服务，打开Swagger UI即可看到TestResp<TestData>的data字段类型已正确显示为TestData。

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