之前在和一些技术同事聊到了接口文档这事，并提到了swagger，收到的反馈有这些：
“很麻烦！接口文档要和代码耦合在一起”
“字段说明要写好几遍！一改要改好多地方！”
"请求参数想描述清楚要写一堆玩意儿！！"
我也看了下，控制器方法上要对每个参数这么描述，确实有点反人类啊！
@ApiImplicitParams({
@ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})
并且对于返回值，往往大多的示例都是封装了一个响应对象，类似：
@Data
public class RespData{
public static final int Success = 1;
public static final int Error = 0;
private int status;
private Object datas = "";
private Object meta = "";
public RespData(int status, Object datas) {
this.status = status;
if(status == Success){
this.datas = datas;
}else{
this.meta = datas;
}
}
public RespData(Exception e){
this.status = Error;
this.meta = e.getMessage();
}
}
结果是最终生成的接口文档，对于返回值描述是这样：
前端人员在阅读文档时，表情应该是这样子的吧
我大概讲一下自己怎么用的吧: （不需要搞那么多工作量，有时候真的是因为不熟悉，看到别人怎么用就只会怎么用）
我的环境： SpringBoot 2.1 + Mybatis plus 3.1.0 + Swagger2 +lombok
首先，入参尽量用对象来承载，不管是get还是post方法，这是好习惯，还可以做一些封装，我这里就封装了一个PageQuery对象，里面有 pageNo，pageSize两个Integer（相比你在所有需要分页查询的方法参数都放这两个变量要优雅一些吧？）
然后，既然是封装了对象， 那就可以不用一大坨@ApiImplicitParams啦！用这个注解 ：@ApiModelProperty 。
@Data
public class ProductQuery extends PageQuery{
@ApiModelProperty(value = "商品类型ID")
private Long typeId;
}另外改造一下数据返回对象，让其支持泛型
public class RespDataT<T>{
public static final int Success = 1;
public static final int Error = 0;
private int status;
private T datas ;
private Object meta = "";
public RespDataT(T datas) {
this.datas = (T)datas;
this.status =Success;
}
public RespDataT(int status, T datas) {
this.status = status;
if(status == Success){
this.datas =(T) datas;
}else{
this.meta = datas;
}
}
public RespDataT(Exception e){
this.status = Error;
this.meta = e.getMessage();
}
}
嗯，再看看控制器中怎么写
@ApiOperation("商品列表")
@GetMapping(path = "/list")
@ResponseBody
public RespDataT<IPage<Product>> list(ProductQuery query) {
try{
Page<Product> page = new Page<>(query.getPage(),query.getPageSize());
IPage<Product> datas = productMapper.getProductPage(page,query);
return new RespDataT<IPage<Product>>(datas);
}catch (Exception e) {
LOGGER.error(e.getMessage(),e);
return new RespDataT<IPage<Product>>(e);
}
}其中，IPage 是 Mybatis plus提供的分页参数， Product 是由Mybatis plus 生成的数据表实体。
另外提一点，Mybatis plus的代码生成器，是可以自动添加 Swagger2 的注解的！！
GlobalConfig gc = new GlobalConfig();
gc.setSwagger2(true);生成的代码：
这样生成的实体，都被添加了 @ApiModelProperty ，也就是说：你只要数据库表的注释写好了，你的API文档的字段说明也就ok了。
最后，看下生成的Swagger文档长什么样子了
请求部分，参数包含了我们继承的 分页参数，实体新加的属性。（分页的对象我没加 @ApiModelProperty ）
然后是文档的返回数据：
后面遇到字段调整，mybatis plus 重新生成一下实体代码，就可以了。
（反正生成的代码，项目中都尽量不会手动去改的，便于维护）
