使用@ApiModel遇到的問(wèn)題及解決
@ApiModel遇到的問(wèn)題
使用 swagger2 中的 @ApiModel 注解不規(guī)范遇到的 swagger 文檔 錯(cuò)亂問(wèn)題：
1. 習(xí)慣
以前使用 swagger2 時(shí), 在出入?yún)?shí)體上添加注解 @ApiModel 時(shí)習(xí)慣性的添加 value = "XXX" 屬性, 舊版本中一直沒(méi)有發(fā)現(xiàn)有什么問(wèn)題.
2. 遇坑
最近在使用 swagger2:2.9.2 版本時(shí), 遇到一個(gè)問(wèn)題, swagger 文檔中的 入?yún)?結(jié)構(gòu)示例中的入?yún)?shù)跟代碼的入?yún)?duì)象中的字段不匹配不一致, 導(dǎo)致接口聯(lián)調(diào)問(wèn)題多
3. 排查
經(jīng)過(guò)排查發(fā)現(xiàn)是因?yàn)?@ApiModel 直接使用不規(guī)范導(dǎo)致的。
- 錯(cuò)誤用法：@ApiModel(value = "用戶信息")
- 正確用法：@ApiModel(description = "用戶信息")
經(jīng)過(guò)排查發(fā)現(xiàn), swagger2 是需要 value 屬性在同一個(gè)服務(wù)全局中保持唯一的, swagger 會(huì)把所有的 API 中的出入?yún)?shí)體列在 swagger 文檔的最下方, 如果存在多個(gè)實(shí)體的 @ApiModel(value = "用戶信息") 注解相同, 那么 swagger 只會(huì)識(shí)別一個(gè), 其他的 實(shí)體 會(huì)被覆蓋, 不會(huì)被顯示, 其他被覆蓋的 實(shí)體在 API 被引用的地方在文檔中會(huì)被識(shí)別的相同名稱的實(shí)體 替代, 導(dǎo)致文檔展示錯(cuò)亂問(wèn)題
4. 解決
使用正確的用法：
@ApiModel(description = "用戶信息"), 如果我們能在代碼規(guī)范中保證實(shí)體名稱不會(huì)重復(fù), value 使用默認(rèn)就好, 所以不再配置, 實(shí)體說(shuō)明使用 description 來(lái)進(jìn)行配置.
@ApiModel和@ApiModelProperty
版本
- springfox-swagger2 (version = 2.9.2)
- swagger-bootstrap-ui (version = 1.9.6)
- swagger-models (version =1.6.1)
@ApiModel
- 使用場(chǎng)景：在實(shí)體類上邊使用，標(biāo)記類時(shí)swagger的解析類
| 屬性名稱 | 數(shù)據(jù)類型 | 默認(rèn)值 | 說(shuō)明 |
|---|---|---|---|
| value | String | 類名 | 為模型提供備用名稱 |
| description | String | " | 提供詳細(xì)的類描述 |
| parent | Class<?> | Void.class | 為模型提供父類以允許描述繼承關(guān)系 |
| discriminator | String | " | 支持模型繼承和多態(tài)，使用鑒別器的字段的名稱，可以斷言需要使用哪個(gè)子類型 |
| subTypes | Class<?>[] | {} | 從此模型繼承的子類型數(shù)組 |
| reference | String | ‘’ | 指定對(duì)應(yīng)類型定義和引用，覆蓋指定的任何其它元數(shù)據(jù) |
@ApiModelProperty
- 使用場(chǎng)景：使用在被 @ApiModel 注解的模型類的屬性上
| 屬性名稱 | 數(shù)據(jù)類型 | 默認(rèn)值 | 說(shuō)明 |
|---|---|---|---|
| value | String | " | 屬性簡(jiǎn)要說(shuō)明 |
| name | String | " | 運(yùn)行覆蓋屬性的名稱，重寫屬性名稱 |
| allowableValues | String | " | 限制參數(shù)可接受的值 |
| access | String | " | 過(guò)濾屬性 |
| notes | String | " | 尚未使用 |
| dataType | String | " | 參數(shù)的數(shù)據(jù)類型 |
| required | boolean | false | 是否必傳 |
| position | int | 0 | 允許在模型中排序?qū)傩?/td> |
| hidden | boolean | false | 隱藏模型屬性 |
| example | String | " | 屬性的示例值 |
| readOnly | boolean | false | 指定模型屬性為只讀，false:非只讀 |
| reference | String | " | 指定對(duì)應(yīng)類型定義的引用，覆蓋指定的任何其他元數(shù)據(jù) |
| allowEmptyValue | boolean | false | 允許傳空置，false：不允許傳空值 |
以上為個(gè)人經(jīng)驗(yàn)，希望能給大家一個(gè)參考，也希望大家多多支持腳本之家。
相關(guān)文章
這篇文章主要介紹了Java中的BigDecimal精度運(yùn)算詳解,Java在java.math包中提供的API類BigDecimal,用來(lái)對(duì)超過(guò)16位有效位的數(shù)進(jìn)行精確的運(yùn)算,雙精度浮點(diǎn)型變量double可以處理16位有效數(shù),但在實(shí)際應(yīng)用中,可能需要對(duì)更大或者更小的數(shù)進(jìn)行運(yùn)算和處理,需要的朋友可以參考下2023-10-10
Java無(wú)界阻塞隊(duì)列DelayQueue詳細(xì)解析
這篇文章主要介紹了Java無(wú)界阻塞隊(duì)列DelayQueue詳細(xì)解析,DelayQueue是一個(gè)支持時(shí)延獲取元素的無(wú)界阻塞隊(duì)列,隊(duì)列使用PriorityQueue來(lái)實(shí)現(xiàn),隊(duì)列中的元素必須實(shí)現(xiàn)Delayed接口,在創(chuàng)建元素時(shí)可以指定多久才能從隊(duì)列中獲取當(dāng)前元素,需要的朋友可以參考下2023-12-12
SpringBoot整合阿里?Druid?數(shù)據(jù)源的實(shí)例詳解
這篇文章主要介紹了SpringBoot整合阿里?Druid?數(shù)據(jù)源，主要講解了手動(dòng)配置方法，結(jié)合實(shí)例代碼給大家介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或工作具有一定的參考借鑒價(jià)值,需要的朋友可以參考下2022-11-11
java?Long類型轉(zhuǎn)為json后數(shù)據(jù)損失精度的處理方式
這篇文章主要介紹了java?Long類型轉(zhuǎn)為json后數(shù)據(jù)損失精度的處理方式，具有很好的參考價(jià)值，希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方，望不吝賜教2022-01-01
這篇文章主要介紹了如何在IntelliJ IDEA開發(fā)環(huán)境中搭建字節(jié)碼和匯編環(huán)境,以便更好地進(jìn)行代碼調(diào)優(yōu)和JVM學(xué)習(xí),首先,介紹了如何配置IntelliJ IDEA以方便查看Java字節(jié)碼文件,接著,詳細(xì)說(shuō)明了如何下載和配置HSDIS插件,以便在IDEA中查看Java方法的匯編代碼2025-01-01
Java Springboot之Spring家族的技術(shù)體系
今天帶大家來(lái)學(xué)習(xí)Spring家族的技術(shù)體系,文中有非常詳細(xì)的圖文介紹及代碼示例,對(duì)正在學(xué)習(xí)java的小伙伴們很有幫助,需要的朋友可以參考下2021-05-05
使用@PathVariable接收兩個(gè)參數(shù)
這篇文章主要介紹了使用@PathVariable接收兩個(gè)參數(shù)的操作，具有很好的參考價(jià)值，希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方，望不吝賜教2021-08-08
SpringBoot 使用Mybatis分頁(yè)插件實(shí)現(xiàn)詳解
這篇文章主要介紹了SpringBoot 使用Mybatis分頁(yè)插件實(shí)現(xiàn)詳解,文中通過(guò)示例代碼介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值,需要的朋友可以參考下2019-10-10
內(nèi)存溢出分為兩大類：OutOfMemoryError和StackOverflowError,以下舉出10個(gè)內(nèi)存溢出的情況,并通過(guò)實(shí)例代碼的方式講解了是如何出現(xiàn)內(nèi)存溢出的,感興趣的可以了解一下2024-01-01
工作中我們經(jīng)常會(huì)用到線程，一般情況下我們讓線程執(zhí)行就完事了，那么你們有沒(méi)有想過(guò)如何去終止一個(gè)正在運(yùn)行的線程呢？本文就來(lái)帶大家一起看看2023-03-03