knife4j swagger 返回值 字段属性说明不显示
1、前言
knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。界面如下:(最新前端UI版:<version>3.0.3</version>)
目标展示如下图:
正常情况下,不管是调试还是文档说明都会显示以上字段说明(除非你没写注解说明)
这里很多朋友碰见的最多的问题主要有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;
}
参考:https://doc.xiaominfo.com/v2/faq/swagger-des-not-found.html
- 字段 属性 knife4j swagger knife4字段 属性knife4j swagger springboot knife4j swagger knife4 knife4j swagger文档knife4 swagger2 swagger knife4j knife4 接口knife4j swagger knife4 接口swagger knife4j文档 文档swagger knife4j knife4 springboot swagger knife4j版本 springboot3 springboot swagger knife4j 参数swagger knife4j knife4