Springboot系列(十三):集成在线接口文档Swagger2(完结篇)

bug菌
631 阅读7分钟

👨‍🎓作者：bug菌
✏️博客：CSDN、掘金、infoQ、51CTO等
🎉简介：CSDN博客专家，C站历届博客之星Top50，掘金/InfoQ/51CTO等社区优质创作者，全网合计8w粉+，对一切技术感兴趣，重心偏Java方向；硬核公众号「 猿圈奇妙屋」，欢迎小伙伴们的加入，一起秃头，一起变强。
..
✍️温馨提醒：本文字数：1999字, 阅读完需：约 5 分钟

嗨，家人们，我是bug菌呀，我又来啦。今天我们来聊点什么咧，OK，接着为大家更《springboot零基础入门教学》系列文章吧。希望能帮助更多的初学者们快速入门！

小伙伴们在批阅文章的过程中如果觉得文章对您有一丝丝帮助，还请别吝啬您手里的赞呀，大胆的把文章点亮👍吧，您的点赞三连(收藏⭐+关注👨‍🎓+留言📃)就是对bug菌我创作道路上最好的鼓励与支持😘。时光不弃🏃🏻‍♀️，创作不停💕，加油☘️

一、前言🔥

环境说明：Windows10 + Idea2021.3.2 + Jdk1.8 + SpringBoot 2.3.1.RELEASE

       我们这期主要是针对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

作用：单个参数描述。

代码演示：

@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 一样，前者是思想，而后者是实现。

... ...

       OK，以上就是这期所有的内容啦，如果有任何问题欢迎评论区批评指正，咱们下期见。

四、往期热门推荐

文末🔥

如果还想要学习更多，小伙伴们可关注bug菌专门为大家创建的专栏《springboot零基础入门教学》，从无到有，从零到一！希望能帮助到更多小伙伴们。

我是bug菌，一名想走👣出大山改变命运的程序猿。接下来的路还很长，都等待着我们去突破、去挑战。来吧，小伙伴们，我们一起加油！未来皆可期，fighting！

感谢认真读完我博客的铁子萌，在这里呢送给大家一句话，不管你是在职还是在读，绝对终身受用。
时刻警醒自己：
抱怨没有用，一切靠自己；
想要过更好的生活，那就要逼着自己变的更强，生活加油！！！

avatar
文章
阅读
粉丝