Swagger注解@ApiModel的巨坑

最近项目开始使用Swagger作为Api文档的编写工具，Swagger确实是为开发工作带来了很多方便。但是偶尔总会出现明明接口说明已经修改了，但在doc.html上总是看到旧的字段描述。甚至有时字段已经删除了，不管怎么重启，怎么清缓存，还是赖着在那里。

期间一直以为是缓存的问题，各种请浏览器缓存，换浏览器，甚至删除操作系统的tmp目录，都是无法解决。导致这期间总是被前端开发人员说我的接口与文档描述不符。心累啊。

今天无意间打开了“Swagger Models”菜单，发现界面上显示的model数量怎么那么少，跟我服务端的代码的类的数量相差较大。所以去看了一下后端代码，并对比了下“Swagger Models”里面的模型详情。终于被我发现了这个巨坑的根本原因，原来我在定义@ApiModel时写的value值时一样的，Swagger并没有报错，而是默默的帮我把两个类的字段合在一起。代码及效果如下图所示：

 

 

 如上面几个示例图所示，如果两个类的ApiModel命名一样，那就有各种误以为是缓存的问题出现了。如两个类有同一个字段，两个字段的描述不一样，却会出现一个覆盖另一个的问题。有时删除掉一个，因为另一个没有删除，会出现以为删不掉的情况。