一、前言🔥
环境说明：Windows10 + Idea2021.3.2 + Jdk1.8 + SpringBoot 2.3.1.RELEASE
二、Swagger常用注解
由于Swagger 是通过注解的方式来生成对应的 API，在接口上我们需要加上各种注解来描述这个接口，所以对它常用的注解我们是必须要清楚的，要不然我讲这些也只是徒劳，
接下来我将关于 Swagger 注解的使用在教程进行详细讲解。请大家好好听~
1、@API
作用：修饰整个类，描述Controller的作用。
代码演示：
@RestController
@RequestMapping("/user")
@Api(tags = "用户管理模块",description = "用户管理模块")
public class UserController {}
演示截图：
2、@ApiOpration
作用：描述一个类的一个方法，或者说一个接口。
代码演示：
@GetMapping("/get-users")
@ApiOperation(value = "不分页查询所有用户信息",notes = "不分页查询所有用户信息")
public List<UserEntity> getUserList() {}
演示截图：
3、@ApiParam
作用：单个参数描述。
代码演示：
@GetMapping("/getUser-by-id")
@ApiOperation(value = "根据用户id查询用户信息",notes = "根据用户id查询用户信息")
public UserEntity getUserById(@RequestParam(name = "userId")@ApiParam("请输入用户id") String userId){ return userMapper.getUserById(userId);
}
演示截图：
4、@ApiModel
作用：用对象来接收参数。
代码演示：
@ApiModel(value = "查询用户参数体",description = "查询用户参数体")
public class QueryUserInfoModel {
}
演示截图：
5、@ApiModelProperty
作用：用对象接收参数时，描述对象的一个字段。
代码演示：
@ApiModelProperty("发件人邮箱账号")
private String sendMailAccount;@ApiModelProperty("收件人邮箱账号")
private String acceptMailAccount;
演示截图：
6、@ApiIgnore
作用：可以用在类、方法上，方法参数中，用来屏蔽某些接口或参数，使其不在页面上显示。
代码演示1：用在类上
@ApiIgnore
@RestController
@RequestMapping("/user")
@Api(tags = "用户管理模块",description = "用户管理模块")
public class UserController {}
代码演示2：用在方法上
@ApiIgnore@GetMapping("/get-users")@ApiOperation(value = "不分页查询db所有用户信息",notes = "不分页查询db所有用户信息")public ListgetUserList() {return userService.getUsers();}
以上这个注解也是经常会被用到，如果接口暂时不上线，或者还未完善，我们就可以加上此注解，这样使用swagger文档的同事就不会看到这个接口，以免造成不必要的麻烦，接口报错啊？这接口怎么逻辑不对？等问题，是不是就很便利，二来你也不需要注释掉或者删除，所以这个注解大家还是要多练练加深印象哈。
**注意：**如下所介绍到的几个不是经常用到，我们就当拓展吧~以了解为主哈。你们不必花时间深入研究。
7、@ApiResponse
作用：在 Rest 接口或类上和 @ApiResponses 组合使用，组装返回参数说明。
8、@ApiResponses
作用:HTTP响应整体描述。
9、@ApiError
作用:发生错误返回的信息。
10、@ApiImplicitParam
作用：一个请求参数。
11、@ApiImplicitParams
作用：多个请求参数 。
... ...
其实还有一部分api，我就一一列举了，靠大家举一反三啦。
三、总结
其实归根到底啊，使用Swagger，就是把相关的信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。而Springfox-swagger,则可以通过扫描代码去生成这个描述文件，连描述文件都不需要再去维护了。所有的信息，都在代码里面了。代码即接口文档，接口文档即代码，在线文档就替我们解决了文档书写及维护的百分之九十的工作，还是很感谢这些开源大佬们做出的贡献。
至于为什么说是Springfox-swagger？其实呢Swagger 就可以看作是一个遵循了 OpenAPI 规范的一项技术，而 springfox 则是这项技术的具体实现。 就好比 Spring 中的 AOP 和 DI 一样，前者是思想，而后者是实现。
