Swagger UI 2.8.0无法正确识别带多态配置的Audience模型

Swagger 2.x系列（包括2.8.0）对Jackson的多态注解（@JsonTypeInfo、@JsonSubTypes）支持并不完全自动，所以需要结合Swagger自身的注解来辅助生成正确的API文档。下面是具体的解决步骤和代码修改方案：

1. 补充Swagger注解到多态模型 #

你需要在父接口和子类上添加Swagger的@ApiModel、@ApiModelProperty注解，明确告知Swagger多态的结构：

修改后的Audience接口 #

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import com.fasterxml.jackson.annotation.JsonTypeInfo;
import com.fasterxml.jackson.annotation.JsonSubTypes;

@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.PROPERTY)
@JsonSubTypes({ 
    @JsonSubTypes.Type(value = AudienceA.class, name = "AudienceA"), 
    @JsonSubTypes.Type(value = AudienceB.class, name = "AudienceB") 
})
@ApiModel(
    value = "Audience",
    discriminator = "@type", // 这里要和Jackson @JsonTypeInfo默认的property名称一致（如果没自定义的话）
    subTypes = {AudienceA.class, AudienceB.class}
)
public interface Audience { 
    @ApiModelProperty(hidden = true) // 隐藏接口方法，避免Swagger展示无用的操作
    void doSomething(); 
}

修改后的AudienceA类 #

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(value = "AudienceA") // 名称要和@JsonSubTypes里的name对应
public class AudienceA implements Audience { 
    @ApiModelProperty(value = "AudienceA专属字符串字段")
    private String someStringField; 
    
    public AudienceA(){ } 
    
    @Override
    @ApiModelProperty(hidden = true)
    public void doSomething(){} 

    // 记得添加getter/setter，Swagger需要通过getter识别字段
    public String getSomeStringField() {
        return someStringField;
    }

    public void setSomeStringField(String someStringField) {
        this.someStringField = someStringField;
    }
}

2. 关键注意点 #

• 鉴别器字段匹配：@ApiModel的discriminator参数必须和Jackson @JsonTypeInfo中指定的property名称完全一致。如果你的@JsonTypeInfo自定义了property = "type"，那这里就要改成discriminator = "type"。
• 子类名称对应：@ApiModel(value = "...")的名称要和@JsonSubTypes.Type里的name参数一致，这样Swagger才能把子类和父接口关联起来。
• 添加Getter/Setter：Swagger是通过类的getter方法来识别字段的，所以必须确保子类的属性有对应的getter/setter方法，否则字段不会在Swagger UI中展示。
• 隐藏无用方法：接口中的doSomething()方法属于业务逻辑，不需要在API文档中展示，用@ApiModelProperty(hidden = true)隐藏即可。

3. 验证效果 #

修改完成后重启服务，打开Swagger UI，你应该能看到：

• Audience模型下会显示鉴别器字段（比如@type），下拉选项包含AudienceA和AudienceB
• 选择对应的子类后，会展示该子类的专属字段（比如AudienceA的someStringField）

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