swagger2的@ApiModel使用不当导致文档展示错乱

问题描述

使用swagger2时发现下面这样写会导致接口显示错误

@Data
@Accessors(chain = true)
@EqualsAndHashCode(callSuper = true)
@ApiModel("插入发票信息")
public class AppInvoiceRecordFuZhuVO extends BaseVo {

    @ApiModelProperty(value = "订单编号集合" , required = false ,example = "['O1365814','O45415615']")
    private List<String> list;
    @ApiModelProperty(value = "发票抬头" , required = false ,example = "1")
    private String invoiceHeader;
}

另一个实体类

@Data
@Accessors(chain = true)
@EqualsAndHashCode(callSuper = true)
@ApiModel("插入发票信息")
public class AppInvoiceRecordInsertReqVO extends BaseVo {
/**
     * 发票抬头
     */
    @ApiModelProperty(value = "发票抬头" , required = false ,example = "发票抬头")
    private String invoiceHeader;
}

---

原因分析：

经过排查发现是因为 @ApiModel 直接使用不规范导致的。

错误用法：多个实体类@ApiModel(value = “插入发票信息”)的value值相同
正确用法：@ApiModel(description = “插入发票信息”)
swagger2 是需要 value 属性在同一个服务全局中保持唯一的, swagger 会把所有的 API 中的出入参实体列在 swagger 文档的最下方, 如果存在多个实体的 @ApiModel(value = “插入发票信息”) 注解相同, 那么 swagger 只会识别一个, 其他的 实体 会被覆盖, 不会被显示, 其他被覆盖的 实体在 API 被引用的地方在文档中会被识别的相同名称的实体替代, 导致文档展示错乱问题

---

解决方案：

使用正确的用法：

@ApiModel(description = “插入发票信息”), 如果我们能在代码规范中保证实体名称不会重复, value 使用默认就好, 所以不再配置, 实体说明使用 description 来进行配置.