Swagger是个测试工具，它能将我们在controller层暴露的接口添加说明。

一.我们可以使用@Api注解，在一个controller类上添加说明。 如下： 那么，访问swagger时，就能看到这个controller类的描述了 二.我们可以通过将@ApiOperation注解，写在controller层的方法上，来说明该方法的作用。

我们可以给实体类的字段添加描述。 那么，我们为什么要给实体类的属性添加描述呢？ 这是因为在开发中，我们的controller层经常用实体类作为出参和入参，添加了描述后，前端人员可以在swaggerUi中调试这个接口时，能够明白这个实体类中各个属性的作用。 使用方法就是把@ApiModelProperty注解定义在你要描述的属性名上面，通过注解的value属性来描述。 方法如下：

对于controller层方法中的参数，我们同样也可以添加描述。 使用到的注解为@ApiImplicitParams()， 在该注解里头，再以数组格式来声明多个@ApiImplicitParam注解，每声明一个代表要对一个参数进行描述。 @ApiImplicitParam注解的介绍如下：

值得注意的是，方法入参有时为普通参数，有时则是对象， 但都是通过@ApiImplicitParam注解来描述的，并且使用起来并无多大区别，下面就举例。

参数是普通类型的情况下

那么我们在swaggerUI就能看到对这些参数的描述了。

在方法的入参参数是对象的情况下，我们进行一个假设； 假设这个对象有三个属性，分为name,age,sex，但我们的实际上只需要前端传来该对象的‘name’值和’age’值。 那么，此时我们通过@ApiImplicitParam注解中的’name’属性，来指定该对象的字属性名字即可。

效果如下，我们在swaggerUi中可以看到有几个加粗了的字段，这些就是我们通过@ApiImplicitParam的required（是否必填）属性指定为true的字段。

对于返回值的参数描述，则需要使用@ApiResponses注解，再以数组形式，在该注解里头使用@ApiResponse注解来对返回值进行描述。 不过和入参描述不同的是，我们对返回值的描述是以一个实体类为描述参照的； 这是因为入参参数那样可以有一个或多个，但返回值就只有一个，不过返回值，也就是对象里头有多个字段。 基于此，我们需要先在用于当作返回值类型的实体类里头，通过@ApiModelProperty注解对实体类的属性值进行描述，可以参考给实体类的字段添加描述。 @ApiResponse的属性如下：

代码如下：

效果如下：

不知道你有注意到没，例子中，我指定的返回值类型虽然为’ForecastProject‘，但是方法中的返回值类型却是’TableDataInfo‘。 这是因为TableDataInfo是一个用于封装响应结果的对象，ForecastProject的数据其实被封装在了TableDataInfo类中的’rows’字段。 那我们为什么不把response属性指定为TableDataInfo类呢？ 这就是工作协调中要灵活多变的地方，因为你把’TableDataInfo‘类当作要描述的返回值类型去给前端调试的话，是没有意义的！ 前端开发人员当然知道需要操作TableDataInfo.rows来取得数据，但描述具体信息的实体类到底是什么结构，它却不知道，因此当然要将具体的实体类当作返回值类型去描述。

参考： https://www.freesion.com/article/1709510261/ https://www.cnblogs.com/h-c-g/p/11004020.html https://blog.csdn.net/jiangyu1013/article/details/83107255 https://blog.51cto.com/u_5634409/2343942 https://blog.csdn.net/qq_25983579/article/details/104532743