使用@ApiModel遇到的问题及解决

目录@ApiModel遇到的问题1. 习惯2. 遇坑3. 排查4. 解决@ApiModel和@ApiModelProperty版本@ApiModel@ApiModelProperty

@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的解析类

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

@ApiModelProperty

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

属性名称数据类型默认值说明valueString&qYAJmwSMKuot;属性简要说明nameString"运行覆盖属性的名称，重写属性名称allowableVhttp://aluesString"限制参数可接受的值accessString"过滤属性notesString"尚未使用dataTypeString"参数的数据类型requiredbooleanfalse是否必传positionint0允许在模型中排序属性hiddenbooleanfalse隐藏模型属性exampleString"属性的示例值readOnlybooleanfalse指定模型属性为只读，false:非只读referenceString"指定对应类型定义的引用，覆盖指定的任何其他元数据allowEmptyValuebooleanfalse允许传空置，false：不允许传空值

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。