【金秋打卡】第二天 Swagger接口文档神器

学习课程名称：Swagger接口文档神器
章节名称：Swagger实战
讲师：晴天哥

课程内容：

1. Swagger注解
2. 如何搭建Swagger
3. SpringBoot整合Swagger
4. Swagger在线测试
5. Swagger值得注意事项

@Api
@Api 注解用于标注一个Controller（Class）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。

@ApiOperation
@ApiOperation 注解在用于对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。

@ApiParam
@ApiParam作用于请求方法上，定义api参数的注解。

@ApiImplicitParams、@ApiImplicitParam
@ApiImplicitParams、@ApiImplicitParam 都可以定义参数.
(1).@ApiImplicitParams：用在请求的方法上，包含一组参数说明
(2).@ApiImplicitParam：对单个参数的说明

@ApiResponses、@ApiResponse
@ApiResponses、@ApiResponse进行方法返回对象的说明。

@ApiModel、@ApiModelProperty
@ApiModel用于描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）。

@ApiModelProperty用来描述一个Model的属性
使用场景
@ApiModel 用在模型类上,对模型类作注解
@ApiModelProperty 用在属性上,对属性作注解

@PathVariable
@PathVariable用于获取get请求url路径上的参数，即参数绑定的作用，通俗的说是url中"?"前面绑定的参数。

注意事项：
1.为了在swagger-ui上看到输出,至少需要两个注解:@Api和@ApiOperation
2.即使只有一个@ApiResponse,也需要使用@ApiResponses包住使用
3.对于@ApiImplicitParam的paramType: query,from域中的值需要使用@RequerstParam获取, header域中的只需要使用@RequestHeader来获取,path域中的值需要使用@PathVariable来获取,body域中的值使用@RequestBody来获取,否则可能出错;而且如果paramType是body,name不能是body,否则有问题,与官方文档中的"if paramType is “body”,the name should be “body” "不符。