1 抛个异常
临下班的时候，前端有人反馈说，怎么对接口的时候 Swagger 文档里看不到对象的具体字段和中文名，这样就得找后端反复去问，额外的沟通成本，很浪费时间。
平时好像有看到过某些接口有字段说明，有些接口没有，一直没放在心上，既然有人提了，那还是来看看到底怎么回事吧。
混入防转防爬防抄袭声明：本文《Swagger 看不到字段注解说明》首发且仅发布于没有名字的博客
2 问题排查
从 Swagger 页面上看了一下，发现到细节：同一个对象，如果是接口入参，就能展示出字段来，但是在分页查询接口的出参中，就没了详情，只展示到封装的 Page 对象这一级。
网上简单一搜，好家伙，很常见的问题嘛，那来一个个排查。
2.1 注解加了吗
别看是一句废话，但确实该优先排查。
2.2 泛型 T 问题
后端定义一些通用的返回对象，大概率会使用到泛型，这里分两种情况。
- 第一种 字段标记了泛型 T
private T data;
public T getData() {
return data;
}
必须注意在其 get 方法的返回也必须是 T，不能是 Object。
- 第二种 类是泛型 T
public class Page<T> {}
必须注意使用到该泛型 Page 的地方，要显式指定 T 的具体类型，使用 ? 会导致不显示。
public R<Page<StudentTO>> page() {}
2.3 不要用注解的 example
@ApiModelProperty(value = "结果", example = "示例会覆盖？？")
private List list;
如果设置 example 的值就会发现
2.4 字段和 get 方法不匹配
其实跟上面讲的泛型类似，这里有常见的两种情况，其中一种就是我这里踩到的坑。
- 第一种 bool 类型字段以 is 开头
编译器或者某些插件自动生成 get 方法时，遇到 is 开头的，不会生成对应的 getIsXXX()。
- 第二种 有自定义
get方法
比如分页对象中，虽然没有定义总页数 totalPage 这个字段，但可以通过总条数和页大小来算，于是定义了一个 getTotalPage() 方法。
这两种情况如果出现，整个类都不会显示具体的字段。