Swagger3(OpenAPI3)注解使用

Swagger2	OpenAPI3	注解位置
@Api	@Tag(name="接口描述")	Controller类之上
@ApiOperation	@Operation(summary="接口方法描述")	Controller方法上
@ApiImplicitParams	@Parameters({@Parameter(description="参数描述")})	Controller方法上
@ApiImplicitParam	@Parameter(name="参数名", description="参数描述")	Controller方法上
@ApiParam	@Parameter(name="参数名",description="参数描述")	Controller方法上
@ApiIgnore	@Parameter(hidden=true)或@Operation(hidden=true)或@Hidden	Controller方法上
@ApiModel	@Schema	DTO类上
@ApiModelProperty	@Schema	DTO属性上

相关知识

DTO：DTO是Data Transfer Object 的简写，既数据传输对象。

DTO模式，是指将数据封装成普通的JavaBeans，在多个J2EE层次之间传输。   DTO类似信使，是同步系统中的Message。  该JavaBeans可以是一个数据模型Model。    

在传统的编程中，我们一般都是前台请求数据，发送到Webservice，然后WebService向数据库发出请求，获取数据，然后一层层返回；模型如下：

这种比较原始的请求方式带来的缺点有很多，多次请求耗费一定的网络资源，减慢效率。如果一次性返回整个实体类，还可能造成数据库表结构的泄漏。

采用DTO模型之后，整个流程就不一样了：

这样带来的好处有：

1.依据现有的类代码，即可方便的构造出DTO对象，而无需重新进行分析。

2.减少请求次数，大大提高效率。

3.按需组织DTO对象，页面需要的字段我才组织，不需要的我不组织，可以避免传输整个表的字段，一定程度上提高了安全性。