Swagger字段屬性說(shuō)明不顯示

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

1.8.9的功能展示如下圖：

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

這里很多朋友碰見(jiàn)的最多的問(wèn)題主要有2個(gè)：

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

不顯示效果可能如下圖：

返回Object不顯示字段屬性

返回Map為何不顯示

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

Swagger只認(rèn)識(shí)定義好的類(lèi)-屬性，所以接口返回Map,對(duì)于Swagger來(lái)說(shuō)是沒(méi)有字段展示的,這種情況同樣適用與返回Object這個(gè)頂級(jí)父類(lèi).這也是為何要適用泛型T的原因

適用泛型T還是不顯示

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

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

private T data;//返回屬性T

返回T類(lèi)型的get方法必須是返回T，有時(shí)候自動(dòng)生成get、setter方法插件等會(huì)將我們的代碼生成返回Object，例如：

public Object getData(){
    return data;
}

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

public T getData(){
    return data;
}

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

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

另外

一般在完成以上情況后,字段說(shuō)明都會(huì)顯示,這里再提醒一下大家,如果已經(jīng)在泛型中強(qiáng)制約束了返回類(lèi)型后,就無(wú)需在注解@ApiOperation中設(shè)置response屬性值，比如如下代碼

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

以上代碼返回了泛型Rest類(lèi)型的List-AlarmResponse集合,但是卻ApiOperation注解中加了response屬性為AlarmResponse.class，這種情況會(huì)造成Ui只顯示AlarmReponse類(lèi)的屬性說(shuō)明，這顯然是不對(duì)的，因?yàn)樗?code>Rest的屬性給忽略了,所以:

一般情況下,是不寫(xiě)注解@ApiOperation中的response屬性值,能少寫(xiě)就少寫(xiě),將剩下的交給springfox-swagger這個(gè)框架,由它自動(dòng)解析生成接口返回類(lèi)型

最后貼一個(gè)簡(jiǎn)單的返回封裝類(lèi)供大家參考(Rest.java)

public class Rest<T> {


    @ApiModelProperty(value = "是否成功")
    private boolean success=true;
    @ApiModelProperty(value = "返回對(duì)象")
    private T data;
    @ApiModelProperty(value = "錯(cuò)誤編號(hào)")
    private Integer errCode;
    @ApiModelProperty(value = "錯(cuò)誤信息")
    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;
    }
}