knife4j swagger2 返回值 字段属性说明不显示 不显示泛型

knife4j swagger2 返回值 字段属性说明不显示

1、前言

  knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。界面如下:(最新前端UI版:<version>3.0.3</version>)

 

 

 

目标展示如下图:

正常情况下,不管是调试还是文档说明都会显示以上字段说明(除非你没写注解说明 or VO里 的字段没有全部标记注解)

这里很多朋友碰见的最多的问题主要有2个:

  • 返回Map|Object为何不显示
  • 使用泛型T还是不显示

不显示效果可能如下图:

返回Object不显示字段属性

返回Map为何不显示

为何返回Map不显示,大家都知道Map是Java里面的集合接口,不管是Map本身还是诸如HashMap等子实现,这类数据对于Swagger来说都是未定义结构的数据

Swagger只认识定义好的类-属性,所以接口返回Map,对于Swagger来说是没有字段展示的,这种情况同样适用与返回Object这个顶级父类.这也是为何要适用泛型T的原因

适用泛型T还是不显示

很多朋友会说我已经使用泛型T了,可是文档上还是不显示,这里主要的原因有以下几点

属性定义必须是泛型T,如下:

private T data;//返回属性T

返回T类型的get方法必须是返回T,有时候自动生成get、setter方法插件等会将我们的代码生成返回Object,例如:

public Object getData(){
    return data;
}

以上是错误的形式,尽管属性中已经定义为T了,正确的方式:

public T getData(){
    return data;
}

最重要的一步,以上步骤完全正确,代码也没有问题,可是ui还是不显示属性,必须在接口层强指定泛型类型(可能是Swagger要求我们写代码要规范吧~~~),如下:

友情提示

在2.0.6等后面的高版本中,由于升级了Springfox基础组件,如果开发者使用类似JRebel这类热加载插件的时候,会出现类字段没有的情况,目前没有办法解决springfox项目与JRebel插件的冲突,建议是不用JRebel

如果以上情况都ok,还是不显示说明,恭喜你发现了SwaggerBootstrapUi的一个bug,欢迎提issue (opens new window)反馈给我,我会搞定它的~~!

另外

一般在完成以上情况后,字段说明都会显示,这里再提醒一下大家,如果已经在泛型中强制约束了返回类型后,就无需在注解@ApiOperation中设置response属性值,比如如下代码

@ApiOperation(value = "查询所有",response=AlarmReponse.class)
@GetMapping("/queryAll")
public Rest<List<AlarmResponse>> queryAll(){
    //more..
}

以上代码返回了泛型Rest类型的List-AlarmResponse集合,但是却ApiOperation注解中加了response属性为AlarmResponse.class,这种情况会造成Ui只显示AlarmReponse类的属性说明,这显然是不对的,因为它把Rest的属性给忽略了,所以:

一般情况下,是不写注解@ApiOperation中的response属性值,能少写就少写,将剩下的交给springfox-swagger这个框架,由它自动解析生成接口返回类型

最后贴一个简单的返回封装类供大家参考(Rest.java (opens new window))

public class Rest<T> {

    @ApiModelProperty(value = "是否成功")
    private boolean success=true;
    @ApiModelProperty(value = "返回对象")
    private T data;
    @ApiModelProperty(value = "错误编号")
    private Integer errCode;
    @ApiModelProperty(value = "错误信息")
    private String message;

    public boolean isSuccess() {
        return success;
    }

    public void setSuccess(boolean success) {
        this.success = success;
    }

    public T getData() {
        return data;
    }

    public void setData(T data) {
        this.data = data;
    }

    public Integer getErrCode() {
        return errCode;
    }

    public void setErrCode(Integer errCode) {
        this.errCode = errCode;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
}

友情提示

在泛型基础封装类中,开发者有两点需要注意:

1、基础封装泛型类中,不能使用@ApiModel注解来约束该泛型类的类名称,因为泛型类一旦用该注解进行约束后,在OpenAPI的结构中,类名称就只有一个,会导致字段属性找不到的情况。错误的代码示例

/*
* 泛型类中不能使用@ApiModel注解,应该去掉
*/
@ApiModel("结果类")
public class Rest<T> {
    //....
}

2、针对泛型T的属性,不应该在使用@ApiModelProperty注解时,赋予example值,错误的代码示例

public class Rest<T> {
    /*
    * 泛型T属性不能赋予example值,因为T有可能是实体类,这样赋值会导致生成的示例值不一致,应该交给框架去解析类结构
    */
    @ApiModelProperty(value = "返回对象",example="Test")
    private T data; 
}

 3、仔细检查 swagger 的扫描包 是否正确?!即: ApiInfo.apiBasePackage() 是否正确❓

 

参考:https://doc.xiaominfo.com/v2/faq/swagger-des-not-found.html

posted @ 2023-08-31 17:38  望)=天涯  阅读(1688)  评论(0编辑  收藏  举报