使用@ApiModel遇到的问题及解决-Java开发

这篇文章主要介绍了使用@ApiModel遇到的问题及解决，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教

@ApiModel遇到的问题

使用 swagger2 中的 @ApiModel 注解不规范遇到的 swagger 文档错乱问题：

1. 习惯

以前使用 swagger2 时, 在出入参实体上添加注解 @ApiModel 时习惯性的添加 value = "XXX" 属性, 旧版本中一直没有发现有什么问题.

2. 遇坑

最近在使用 swagger2:2.9.2 版本时, 遇到一个问题, swagger 文档中的入参结构示例中的入参参数跟代码的入参对象中的字段不匹配不一致, 导致接口联调问题多

3. 排查

经过排查发现是因为 @ApiModel 直接使用不规范导致的。

错误用法：@ApiModel(value = "用户信息")
正确用法：@ApiModel(description = "用户信息")

经过排查发现, swagger2 是需要 value 属性在同一个服务全局中保持唯一的, swagger 会把所有的 API 中的出入参实体列在 swagger 文档的最下方, 如果存在多个实体的 @ApiModel(value = "用户信息") 注解相同, 那么 swagger 只会识别一个, 其他的实体会被覆盖, 不会被显示, 其他被覆盖的实体在 API 被引用的地方在文档中会被识别的相同名称的实体替代, 导致文档展示错乱问题

4. 解决

使用正确的用法：

@ApiModel(description = "用户信息"), 如果我们能在代码规范中保证实体名称不会重复, value 使用默认就好, 所以不再配置, 实体说明使用 description 来进行配置.

@ApiModel和@ApiModelProperty

版本

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

@ApiModel

使用场景：在实体类上边使用，标记类时swagger的解析类

属性名称	数据类型	默认值	说明
value	String	类名	为模型提供备用名称
description	String	"	提供详细的类描述
parent	Class<?>	Void.class	为模型提供父类以允许描述继承关系
discriminator	String	"	支持模型继承和多态，使用鉴别器的字段的名称，可以断言需要使用哪个子类型
subTypes	Class<?>[]	{}	从此模型继承的子类型数组
reference	String	‘’	指定对应类型定义和引用，覆盖指定的任何其它元数据

@ApiModelProperty

使用场景：使用在被 @ApiModel 注解的模型类的属性上

属性名称	数据类型	默认值	说明
value	String	"	属性简要说明
name	String	"	运行覆盖属性的名称，重写属性名称
allowableValues	String	"	限制参数可接受的值
access	String	"	过滤属性
notes	String	"	尚未使用
dataType	String	"	参数的数据类型
required	boolean	false	是否必传
position	int	0	允许在模型中排序属性
hidden	boolean	false	隐藏模型属性
example	String	"	属性的示例值
readOnly	boolean	false	指定模型属性为只读，false:非只读
reference	String	"	指定对应类型定义的引用，覆盖指定的任何其他元数据
allowEmptyValue	boolean	false	允许传空置，false：不允许传空值