Swagger字段屬性說明不顯示

不管是在SwaggerBootstrapUi以前的版本中,還是在SwaggerBootstrapUi的1.8.9版本發(fā)布新功能字段注釋逐行顯示時,很多朋友都會問為啥自己的UI文檔上不顯示注釋.

1.8.9的功能展示如下圖：

正常情況下,不管是調(diào)試還是文檔說明都會顯示以上字段說明(除非你沒寫注解說明)

這里很多朋友碰見的最多的問題主要有2個：

• 返回Map|Object為何不顯示
• 使用泛型T還是不顯示

不顯示效果可能如下圖：

返回Object不顯示字段屬性

返回Map為何不顯示

為何返回Map不顯示,大家都知道Map是Java里面的集合接口,不管是Map本身還是諸如HashMap等子實現(xiàn),這類數(shù)據(jù)對于Swagger來說都是未定義結(jié)構(gòu)的數(shù)據(jù)

Swagger只認識定義好的類-屬性，所以接口返回Map,對于Swagger來說是沒有字段展示的,這種情況同樣適用與返回Object這個頂級父類.這也是為何要適用泛型T的原因

適用泛型T還是不顯示

很多朋友會說我已經(jīng)使用泛型T了,可是文檔上還是不顯示,這里主要的原因有以下幾點

屬性定義必須是泛型T，如下：

private T data;//返回屬性T

返回T類型的get方法必須是返回T，有時候自動生成get、setter方法插件等會將我們的代碼生成返回Object，例如：

public Object getData(){
    return data;
}

以上是錯誤的形式,盡管屬性中已經(jīng)定義為T了，正確的方式：

public T getData(){
    return data;
}

最重要的一步,以上步驟完全正確,代碼也沒有問題,可是ui還是不顯示屬性，必須在接口層強指定泛型類型(可能是Swagger要求我們寫代碼要規(guī)范吧~~~),如下：

如果以上情況都ok，還是不顯示說明,恭喜你發(fā)現(xiàn)了SwaggerBootstrapUi的一個bug，歡迎提issue反饋給我,我會搞定它的~~！

另外

一般在完成以上情況后,字段說明都會顯示,這里再提醒一下大家,如果已經(jīng)在泛型中強制約束了返回類型后,就無需在注解@ApiOperation中設(shè)置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)

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;
    }
}