使用 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
来进行配置.