使用@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的解析类
属性名称 数据类型 默认值 说明
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：不允许传空值

以上为个人经验，希望能给大家一个参考，也希望大家多多支持我们。

赞 (0)

相关推荐

  • Swagger注解-@ApiModel和@ApiModelProperty的用法

    目录 @ApiModel 使用场景 概述 属性 @ApiModelProperty 使用场景 概述 属性 Swagger踩坑@ApiModel注解问题 @ApiModel 使用场景 在实体类上边使用,标记类时swagger的解析类 概述 提供有关swagger模型的其它信息,类将在操作中用作类型时自动内省 属性 属性名称 数据类型 默认值 说明 value String 类名 为模型提供备用名称 description String “” 提供详细的类描述 parent Class<?> pa

  • SpringBoot中的@ApiModelProperty注解作用

    目录 @ApiModelProperty注解作用 主要字段说明 举个简单的例子 @ApiModelProperty()失效 解决方法 @ApiModelProperty注解作用 @ApiModelProperty()注解用于方法.字段,表示对model属性的说明或者数据操作更改,以下是它的源码: // IntelliJ API Decompiler stub source generated from a class file // Implementation of methods is no

  • swagger注解@ApiModelProperty失效情况的解决

    swagger注解@ApiModelProperty失效情况的解决

    目录 swagger注解@ApiModelProperty失效 swagger 版本 2.29.2 解决方式: 小写字段名 @ApiModelProperty注解的使用 下面是它内部的常用属性 swagger注解@ApiModelProperty失效 swagger 版本 2.29.2 解决方式: 小写字段名 @ApiModelProperty注解的使用 首先要知道@ApiModelProperty是swagger的注解,它的作用是添加和操作属性模块的数据 下面是它内部的常用属性 1.value

  • swagger @ApiModel添加实体类不生效的解决

    swagger @ApiModel添加实体类不生效的解决

    目录 @ApiModel添加实体类不生效 Models实体类无法显示 解决办法 @ApiModel添加实体类不生效 swagger, @ApiModel, Models, 实体类无法加载 在使用swagger时, 以为加上@ApiModel在实体类上就可以在swagger-ui.html的Models里面显示. 但是我创建了很多实体类, 但怎么也只显示了一个??? Models中无论如何只有User这一个实体类. 后来发现不是加上@ApiModel就可以加入Models中的,必须要在contro

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

    目录 @ApiModel遇到的问题 1. 习惯 2. 遇坑 3. 排查 4. 解决 @ApiModel和@ApiModelProperty 版本 @ApiModel @ApiModelProperty @ApiModel遇到的问题 使用 swagger2 中的 @ApiModel 注解不规范遇到的 swagger 文档 错乱问题: 1. 习惯 以前使用 swagger2 时, 在出入参实体上添加注解 @ApiModel 时习惯性的添加 value = "XXX" 属性, 旧版本中一直没

  • 解决Swagger2返回map复杂结构不能解析的问题

    解决Swagger2返回map复杂结构不能解析的问题

    今天有同事用swagger2开发时,有一方法返回Map<String,List<Object>>出现无法解析错误. Pom.xml引入的swagger版本如下: <!--swagger start--> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-annotations</artifactId> <version>1.

  • 解决Swagger修改请求对象字段文档不更新问题

    解决Swagger修改请求对象字段文档不更新问题

    目录 解决方法 描述 解决方法 有两个对象用了同一个@ApiModel的value值 描述 今天发现不管怎么修改如下对象,接口显示总是不变 @Data @NoArgsConstructor @AllArgsConstructor @ApiModel(value = "账单查询对象",description = "请求参数类") public class QueryBillVO { @ApiModelProperty(value = "页码",ex

  • 解决springboot引入swagger2不生效问题

    目录 问题描述: springboot引入swagger2的步骤: ①引入依赖 ②编写Swagger2的配置类 ③在controller中添加注解:按需添加注解 ④在model(pojo)上加注解,按需添加 一些注解的使用 今天遇到跟同事遇到一个由于失误导致的问题,也可以说比较难发现了.在此记录一下(我们用的springboot是2.0.3,swagger是2.2.2) 问题描述: swagger修改title,description等都不生效.并且启动springboot,没有有去加载swag

  • spring boot创建项目包依赖问题的解决

    spring boot创建项目包依赖问题的解决

    今天捣腾了spring boot,按照官网案例,缺发现本地无论包依赖出现问题,并且无法启动,一整天在踩maven的坑,记录下这个血的教训. 1.spring-core依赖包问题 运行application,发现缺少依赖的spring-core包: 但是spring boot的包都是通过parent的starter引入的,通过mvn denpendency:tree查看项目的jar依赖信息:  发现spring-core依赖包是存在的,但是为什么运行的时候回报错找不到类. 倒腾了一个下午试过各种方

  • Oracle dbca时报：ORA-12547: TNS:lost contact错误的解决

    前言 最近在工作中遇到了一个问题,错误是Oracle dbca时报错:ORA-12547: TNS:lost contact,通过查找相关的资料终于找到了解决的方法,下面分享给大家,话不多说了,来一起看看详细的介绍吧. 环境: OS:RHEL6.5 x86-64bit DB:11.2.0.4 for Linux 86-64bit 思路: DBCA报错,首先看DBCA的日志,日志中也是报ORA-12547: TNS:lost contact 于是再sqlplus / as sysdba敲回车,也是

  • iOS11 SectionHeader 胡乱移动且滑动时出现重复内容的解决方法

    升级到iOS 11后,痛苦的事情多起来了,以前版本没有的出现问题的代码,经过Xcode 9一编译,千万草泥马奔腾而过: 今天碰到一个奇葩问题,直接进入主题: 问题描述: -(CGFloat)tableView:(UITableView *)tableView heightForHeaderInSection:(NSInteger)section { return 12; } -(UIView *)tableView:(UITableView *)tableView viewForHeaderIn

  • 解决option标签selected="selected"属性失效的问题

    要在select标签上面加上autocomplete="off"关闭自动完成,不然浏览器每次刷新后将自动选择上一次关闭时的option,这样默认属性selected="selected"就会失效啦 要记住每次遇到select标签时就最好要加上autocomplete="off"这一项 以上这篇解决option标签selected="selected"属性失效的问题就是小编分享给大家的全部内容了,希望能给大家一个参考,也希望大家

  • 解决Ajax加载JSon数据中文乱码问题

    一.问题描述 使用zTree的异步刷新父级菜单时,服务器返回中文乱码,但项目中使用了SpringMvc,已经对中文乱码处理,为什么还会出现呢? 此处为的异步请求的配置: Java代码 async: { enable: true, url: basePath + '/sysMenu/listSysMenu', autoParam: ["id=parentId"] } SpringMvc中文字符处理: Java代码 <mvc:annotation-driven> <mvc

随机推荐