如何在Swagger中配置泛型类作为API端点的返回类型？

嘿，我刚好碰到过一模一样的问题！Java的泛型类型擦除确实坑，Swagger没法直接识别QueryResult<MyType>.class这种带泛型的类型，导致生成的文档里只显示QueryResult而看不到实际的MyType结构。给你几个实用的解决办法：

方法1：创建泛型的具体子类（最稳妥） #

因为Java不允许直接获取带泛型参数的Class对象，我们可以简单创建一个继承自泛型类的具体子类，专门用于Swagger文档：

// 专门为Swagger创建的子类，无需额外业务代码
public class MyTypeQueryResult extends QueryResult<MyType> {}

然后修改API方法里的@ApiOperation配置：

@GET
@Path("/query")
@ApiOperation(response = MyTypeQueryResult.class, value = "通过GET查询数据")
public QueryResult<MyType> queryHttpGet() {
    return new QueryResult<MyType>();
}

这样Swagger就能正确识别到MyType作为泛型的实际类型，生成的文档里会展示完整的QueryResult<MyType>结构。

方法2：用Swagger注解显式指定泛型类型 #

如果不想创建额外的子类，可以在QueryResult类上通过@ApiModel和@ApiModelProperty来指定泛型的实际类型：
先给泛型类加上注解，再对泛型字段标注具体的数据类型：

@ApiModel(description = "通用查询结果返回类")
public class QueryResult<T> {
    // 显式指定该字段的实际类型为MyType
    @ApiModelProperty(dataType = "MyType", description = "查询到的数据列表")
    private List<T> data;
    
    @ApiModelProperty(description = "总记录数")
    private long total;
    // getter、setter省略
}

API方法保持原配置即可：

@GET
@Path("/query")
@ApiOperation(response = QueryResult.class, value = "通过GET查询数据")
public QueryResult<MyType> queryHttpGet() {
    return new QueryResult<MyType>();
}

这种方法适合不想新增类的场景，但要注意：如果同一个泛型类在不同接口里对应不同的实际类型，这种方式灵活性会差一些。

方法3：使用Swagger的@ApiResponse配合泛型容器 #

如果你的QueryResult是用来包裹列表数据的，还可以用@ApiResponse的responseContainer参数指定容器类型，同时关联实际数据类型：

@GET
@Path("/query")
@ApiOperation(value = "通过GET查询数据")
@ApiResponse(code = 200, message = "查询成功", response = MyType.class, responseContainer = "QueryResult")
public QueryResult<MyType> queryHttpGet() {
    return new QueryResult<MyType>();
}

不过这个方法对Swagger版本有要求，建议在Swagger 2.x及以上版本使用。

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