使用@ApiModel遇到的問題及解決

更新時(shí)間：2022年06月14日 10:58:42 作者：Qbaiwan

這篇文章主要介紹了使用@ApiModel遇到的問題及解決，具有很好的參考價(jià)值，希望對大家有所幫助。如有錯(cuò)誤或未考慮完全的地方，望不吝賜教

@ApiModel遇到的問題

使用 swagger2 中的 @ApiModel 注解不規(guī)范遇到的 swagger 文檔錯(cuò)亂問題：

1. 習(xí)慣

以前使用 swagger2 時(shí), 在出入?yún)?shí)體上添加注解 @ApiModel 時(shí)習(xí)慣性的添加 value = "XXX" 屬性, 舊版本中一直沒有發(fā)現(xiàn)有什么問題.

2. 遇坑

最近在使用 swagger2:2.9.2 版本時(shí), 遇到一個(gè)問題, swagger 文檔中的入?yún)?結(jié)構(gòu)示例中的入?yún)?shù)跟代碼的入?yún)ο笾械淖侄尾黄ヅ洳灰恢? 導(dǎo)致接口聯(lián)調(diào)問題多

3. 排查

經(jīng)過排查發(fā)現(xiàn)是因?yàn)?@ApiModel 直接使用不規(guī)范導(dǎo)致的。

錯(cuò)誤用法：@ApiModel(value = "用戶信息")
正確用法：@ApiModel(description = "用戶信息")

經(jīng)過排查發(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ò)亂問題

4. 解決

使用正確的用法：

@ApiModel(description = "用戶信息"), 如果我們能在代碼規(guī)范中保證實(shí)體名稱不會(huì)重復(fù), value 使用默認(rèn)就好, 所以不再配置, 實(shí)體說明使用 description 來進(jìn)行配置.

@ApiModel和@ApiModelProperty

版本

springfox-swagger2 (version = 2.9.2)
swagger-bootstrap-ui (version = 1.9.6)
swagger-models (version =1.6.1)

@ApiModel

使用場景：在實(shí)體類上邊使用，標(biāo)記類時(shí)swagger的解析類

屬性名稱	數(shù)據(jù)類型	默認(rèn)值	說明
value	String	類名	為模型提供備用名稱
description	String	"	提供詳細(xì)的類描述
parent	Class<?>	Void.class	為模型提供父類以允許描述繼承關(guān)系
discriminator	String	"	支持模型繼承和多態(tài)，使用鑒別器的字段的名稱，可以斷言需要使用哪個(gè)子類型
subTypes	Class<?>[]	{}	從此模型繼承的子類型數(shù)組
reference	String	‘’	指定對應(yīng)類型定義和引用，覆蓋指定的任何其它元數(shù)據(jù)

@ApiModelProperty

使用場景：使用在被 @ApiModel 注解的模型類的屬性上

屬性名稱	數(shù)據(jù)類型	默認(rèn)值	說明
value	String	"	屬性簡要說明
name	String	"	運(yùn)行覆蓋屬性的名稱，重寫屬性名稱
allowableValues	String	"	限制參數(shù)可接受的值
access	String	"	過濾屬性
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	"	指定對應(yīng)類型定義的引用，覆蓋指定的任何其他元數(shù)據(jù)
allowEmptyValue	boolean	false	允許傳空置，false：不允許傳空值