前言

swagger ui是一個(gè)采用注解驅(qū)動(dòng)的接口文檔工具，目前已支持標(biāo)準(zhǔn)的open api v3規(guī)范協(xié)議，所以不僅可以在java項(xiàng)目里使用，每個(gè)語(yǔ)言都有相應(yīng)的open api實(shí)現(xiàn)。項(xiàng)目集成swagger后，可以生成導(dǎo)出open api v3格式化的元數(shù)據(jù)集，有了這個(gè)接口元數(shù)據(jù)，你可以在任何支持v3協(xié)議的ui上展示你的api信息。在前后端分離的項(xiàng)目中，swagger ui的出現(xiàn)，大大提高了前后端聯(lián)調(diào)的效率。

swagger ui在解析注解標(biāo)注的元數(shù)據(jù)信息時(shí)，特別場(chǎng)景下會(huì)拋異常，而且拋的異常沒(méi)有直觀的有價(jià)值的異常信息，所以深入的debug了一番，雖然最后問(wèn)題解決很簡(jiǎn)單，但是過(guò)程非常曲折。故將bug定位過(guò)程記錄在此。

• 影響的Swagger版本：1.5.x
• Swagger core：https://github.com/swagger-api/swagger-core

異常信息

這個(gè)異常只會(huì)在加載swagger-ui的頁(yè)面時(shí)會(huì)拋出，每次刷新頁(yè)面，獲取一次api接口就會(huì)觸發(fā)一次異常。

異常分析

@JsonProperty("x-example")
public Object getExample() {
    if (example == null) {
        return null;
 }
    try {
        if (BaseIntegerProperty.TYPE.equals(type)) {
            return Long.valueOf(example);
 } else if (DecimalProperty.TYPE.equals(type)) {
            return Double.valueOf(example);
 } else if (BooleanProperty.TYPE.equals(type)) {
            if ("true".equalsIgnoreCase(example) || "false".equalsIgnoreCase(defaultValue)) {
                return Boolean.valueOf(example);
 }
        }
    } catch (NumberFormatException e) {
        LOGGER.warn(String.format("Illegal DefaultValue %s for parameter type %s", defaultValue, type), e);
 }
    return example;
}

如上是異常相關(guān)的代碼。從異常信息表象來(lái)看，是一個(gè)強(qiáng)轉(zhuǎn)導(dǎo)致的問(wèn)題，代碼試圖將一個(gè)空的字符串轉(zhuǎn)換成數(shù)值類(lèi)型導(dǎo)致異常拋出。并且是getExample時(shí)拋出的異常，這里需要了解swagger ui的加載過(guò)程和基礎(chǔ)架構(gòu)才能直接定位。swagger中的example是為了在生成的api doc中，給出相關(guān)字段的調(diào)用示例，并在觸發(fā)接口調(diào)用時(shí)，默認(rèn)自動(dòng)填充example的值。這里顯然是哪個(gè)地方的example設(shè)置不合理導(dǎo)致的異常。那么，接下來(lái)要做的就是找到這個(gè)空字符串的原始代碼。

DEBUG找到真實(shí)原因

借助IDEA的debug功能，點(diǎn)擊異常后面的create breakpoint，在觸發(fā)異常的地方打上斷點(diǎn)。觸發(fā)異常，進(jìn)入斷點(diǎn)，獲取到了關(guān)鍵信息

一個(gè)被描述為app id的字段，用這個(gè)信息全局搜索，得到如下的結(jié)果：

有三個(gè)相關(guān)的Model實(shí)體，首先，這三個(gè)Model的appId字段都沒(méi)有設(shè)置過(guò)example屬性，所以，到這一步，可以先下一個(gè)小的結(jié)論，不是我們?cè)O(shè)置的example導(dǎo)致的問(wèn)題，默認(rèn)在不設(shè)置的情況下，example的默認(rèn)值就是空字符串。然后肯定只有其中一個(gè)有問(wèn)題，因?yàn)楫惓Ｖ粫?huì)觸發(fā)一次。在不知道結(jié)果情況下，依次對(duì)這三個(gè)Model的appId字段加上正確的example描述，經(jīng)測(cè)試，只有GetAppBannerRequestDTO加上時(shí)，異常才消失，罪魁禍?zhǔn)拙褪撬恕５?，為什么呢？其他兩個(gè)Model為啥就沒(méi)有問(wèn)題呢？在博主交叉測(cè)驗(yàn)后，發(fā)現(xiàn)了最終的原因。

結(jié)論及注意事項(xiàng)

當(dāng)Model作用于請(qǐng)求的接收參數(shù)時(shí)，并且請(qǐng)求的類(lèi)型為GET，那么Swagger Ui會(huì)自動(dòng)收集Model所有屬性的examole參數(shù)，因?yàn)檫@個(gè)參數(shù)是字符串類(lèi)型，所以會(huì)做一個(gè)類(lèi)型轉(zhuǎn)換動(dòng)作。當(dāng)字段類(lèi)型為數(shù)值類(lèi)型，又有沒(méi)手動(dòng)設(shè)置example的值，那么Swagger框架拿到的是個(gè)空字符串，強(qiáng)轉(zhuǎn)空字符串就拋異常了。而如果請(qǐng)求是POST，就不會(huì)觸發(fā)這段邏輯，所以同為攜帶數(shù)值類(lèi)型DTO的ImgReplaceRequestDTO沒(méi)有問(wèn)題。如果不是接收參數(shù)，作為響應(yīng)參數(shù)，也不會(huì)觸發(fā)這段邏輯，故而AppBannerResponseVO也就沒(méi)有問(wèn)題了。所以，需要注意的就是當(dāng)DTO作用于GET請(qǐng)求的接收參數(shù)時(shí)，切記給所有的數(shù)值類(lèi)型加上正確的example屬性

后記

博主認(rèn)為這里屬于一個(gè)設(shè)計(jì)缺陷，而不是我們的使用問(wèn)題。在獲取example的邏輯里，第一段代碼就判斷了example是否為null。這表明了example有可能為空，但是默認(rèn)值卻設(shè)置了一個(gè)空字符串。代表不手動(dòng)將example設(shè)置為null，這段判null返回的邏輯就永遠(yuǎn)跑不到，而且沒(méi)人會(huì)這么做，手動(dòng)給example設(shè)置為null。況且，在觸發(fā)異常的這種場(chǎng)景下，框架不能強(qiáng)制使用者設(shè)置example這種操作。在github倉(cāng)庫(kù)追蹤這塊代碼發(fā)現(xiàn)，目前Swagger ui已經(jīng)邁入了3.x版本，全面基于open api v3協(xié)議規(guī)范設(shè)計(jì)。所以，這部分代碼完全不一樣了。而存檔的1.5x版本這個(gè)問(wèn)題依舊。

下面是3.x的處理方式，雖然example的默認(rèn)值還是“”。但是通過(guò)NotBlank判斷了下，所以不會(huì)觸發(fā)異常了

為啥不直接升級(jí)3.X？

3.x版本既然已經(jīng)修復(fù)了，為啥不直接升級(jí)到3.x版本呢？可能有人會(huì)有這個(gè)疑問(wèn)。Swagger3.x版本屬于一個(gè)大跨度的迭代版本，和之前的版本完全不兼容，3.x主要面向了open api v3規(guī)范協(xié)議設(shè)計(jì)實(shí)現(xiàn)，注解實(shí)體等模型都是一一對(duì)應(yīng)的。而在這個(gè)版本之前的1.5x系列版本是Swagger自己設(shè)計(jì)的api模型。所以代碼層上面完全不兼容，升級(jí)的工作量會(huì)非常大。不過(guò)，新項(xiàng)目還是推薦使用3.x版本，這個(gè)版本的api數(shù)據(jù)更通用?？梢愿鶕?jù)api的數(shù)據(jù)生成各種語(yǔ)言的客戶(hù)端包。就像proto生成客戶(hù)端包一樣。

以上就是Swagger異常定位紀(jì)實(shí)Swagger設(shè)計(jì)問(wèn)題分析的詳細(xì)內(nèi)容，更多關(guān)于Swagger異常定位Swagger設(shè)計(jì)的資料請(qǐng)關(guān)注腳本之家其它相關(guān)文章！

最新評(píng)論