Spring Boot中如何让Swagger UI展示抽象类DTO的真实响应详情

我有一个Spring Boot应用的REST API，返回的Response对象定义如下：

public class Response {
    private DTO data;
    private Error error;
}

其中DTO是所有DTO的抽象类：

public abstract class DTO { }

它的子类示例：

public class CountryDTO extends DTO {
  private Long id;
  private String code;
  private String name;
}

pom.xml中Swagger依赖配置：

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>

在Swagger UI中查看API文档时，响应仅显示：

{
  "data": {},
  "error": {
    "message": "string"
  }
}

无法展示data字段对应的真实DTO（比如CountryDTO）的JSON结构，请问如何让Swagger UI显示正确的响应结构？

解决方案 #

方法1：通过@ApiResponse指定具体响应类型 #

在Controller方法上使用@ApiResponse注解的response属性，明确声明包含具体DTO的Response子类。由于泛型擦除机制，Swagger无法自动识别抽象类的实际子类，需显式指定：

1. 创建继承自Response的子类，绑定具体DTO类型：

public class CountryResponse extends Response {
    private CountryDTO data;

    // 实现构造方法、getter和setter
}

2. 在Controller接口上标注该子类：

@GetMapping("/countries/{id}")
@ApiResponse(responseCode = "200", description = "成功获取国家信息", 
             response = CountryResponse.class)
public Response getCountry(@PathVariable Long id) {
    // 业务逻辑：返回包含CountryDTO的Response实例
}

配置后，Swagger UI会展示CountryDTO的完整字段结构。

方法2：为抽象类DTO添加Jackson注解 #

通过@JsonTypeInfo和@JsonSubTypes注解，告知Jackson和Swagger抽象类的所有子类，自动生成包含子类结构的文档：

import com.fasterxml.jackson.annotation.JsonSubTypes;
import com.fasterxml.jackson.annotation.JsonTypeInfo;

@JsonTypeInfo(
    use = JsonTypeInfo.Id.NAME,
    include = JsonTypeInfo.As.PROPERTY,
    property = "type" // 用于标识子类类型的字段名，可自定义
)
@JsonSubTypes({
    @JsonSubTypes.Type(value = CountryDTO.class, name = "country")
})
public abstract class DTO { }

此方法同时支持Jackson的序列化/反序列化，Swagger会展示所有注册子类的可能结构。

方法3：配置Springfox的TypeResolver #

通过Swagger配置类，手动绑定Response与具体DTO的类型关系，无需修改现有实体类：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.TypeResolver;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api(TypeResolver typeResolver) {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.basePackage("你的controller包路径"))
                .paths(PathSelectors.any())
                .build()
                .additionalModels(typeResolver.resolve(Response.class, CountryDTO.class));
    }
}

additionalModels方法会让Swagger识别Response中data字段的实际类型为CountryDTO。

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