16. 集成Swagger2 - 完结篇
一、前言🔥
我们这期主要是针对springboot如何集成swagger接口文档进行整体复盘，及给大家科普下swagger常用核心注解吧。
我们上两期，主要是为大家演示了，如何在springboot架构的基础上集成swagger在线接口文档，再到实际使用常用api进行演示及在线文档出现的一些ui变化。
如果有小伙伴中途插入直接看到了这篇，我肯定是要建议你回头看上两期的，毕竟bug菌的教学从来都是以循序渐进式的层层递进，不会一口气给大家灌输太多的知识点，目的只是为了一提升读者阅读感，二是直接消化，三是为了不让大家有阅读负担...
每天掌握一个知识点，就够啦。如果小伙伴们觉得这种方式不妥，那你们也可以提出来，我主要是为了服务大家而服务，如果有更好的建议，我一定会采取。
接下来，我再给大家讲解一下，集成swagger项目中所用到的一些model Api吧，大家请跟我来，具有很好的科普价值，也是日常开发所用，大家好好学吼。
二、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
作用：单个参数描述。
代码演示：
less复制代码@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
作用：用对象来接收参数。
代码演示：
kotlin复制代码@ApiModel(value = "查询用户参数体",description = "查询用户参数体")
public class QueryUserInfoModel {
}演示截图：
5、@ApiModelProperty
作用：用对象接收参数时，描述对象的一个字段。
代码演示：
kotlin复制代码@ApiModelProperty("发件人邮箱账号")
private String sendMailAccount;
@ApiModelProperty("收件人邮箱账号")
private String acceptMailAccount;演示截图：
6、@ApiIgnore
作用：可以用在类、方法上，方法参数中，用来屏蔽某些接口或参数，使其不在页面上显示。
代码演示1：用在类上
less复制代码@ApiIgnore
@RestController
@RequestMapping("/user")
@Api(tags = "用户管理模块",description = "用户管理模块")
public class UserController {
}代码演示2：用在方法上
less复制代码 @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 一样，前者是思想，而后者是实现。