使用@ApiModel遇到的问题及解决
更新时间：2022年06月14日 10:58:42 作者：Qbaiwan
这篇文章主要介绍了使用@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：不允许传空值 |
以上为个人经验，希望能给大家一个参考，也希望大家多多支持脚本之家。
相关文章
这篇文章主要介绍了Java中的BigDecimal精度运算详解,Java在java.math包中提供的API类BigDecimal,用来对超过16位有效位的数进行精确的运算,双精度浮点型变量double可以处理16位有效数,但在实际应用中,可能需要对更大或者更小的数进行运算和处理,需要的朋友可以参考下2023-10-10
这篇文章主要介绍了Java无界阻塞队列DelayQueue详细解析,DelayQueue是一个支持时延获取元素的无界阻塞队列,队列使用PriorityQueue来实现,队列中的元素必须实现Delayed接口,在创建元素时可以指定多久才能从队列中获取当前元素,需要的朋友可以参考下2023-12-12
这篇文章主要介绍了SpringBoot整合阿里 Druid 数据源，主要讲解了手动配置方法，结合实例代码给大家介绍的非常详细，对大家的学习或工作具有一定的参考借鉴价值,需要的朋友可以参考下2022-11-11
这篇文章主要介绍了java Long类型转为json后数据损失精度的处理方式，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教2022-01-01
这篇文章主要介绍了如何在IntelliJ IDEA开发环境中搭建字节码和汇编环境,以便更好地进行代码调优和JVM学习,首先,介绍了如何配置IntelliJ IDEA以方便查看Java字节码文件,接着,详细说明了如何下载和配置HSDIS插件,以便在IDEA中查看Java方法的汇编代码2025-01-01
今天带大家来学习Spring家族的技术体系,文中有非常详细的图文介绍及代码示例,对正在学习java的小伙伴们很有帮助,需要的朋友可以参考下2021-05-05
这篇文章主要介绍了使用@PathVariable接收两个参数的操作，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教2021-08-08
这篇文章主要介绍了SpringBoot 使用Mybatis分页插件实现详解,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下2019-10-10
内存溢出分为两大类：OutOfMemoryError和StackOverflowError,以下举出10个内存溢出的情况,并通过实例代码的方式讲解了是如何出现内存溢出的,感兴趣的可以了解一下2024-01-01
工作中我们经常会用到线程，一般情况下我们让线程执行就完事了，那么你们有没有想过如何去终止一个正在运行的线程呢？本文就来带大家一起看看2023-03-03
最新评论