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

bug菌
1,031 阅读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

        由于我们在上一期进行了swagger配置讲解，这期我们就不再赘述，要是这期新加入的小伙伴，还请先看完我的上期文章教学，这样能少走弯路，好吧？

        接下来，我们就进入正题啦。大家准备好了没？

二、如何生成Swagger文档

        上一期我们已经能正常访问swagger在线文档，但是文档空空如也，对不对，接下来我就教大家怎么把相关的接口都给自动生成到文档里头，而且还有一个很好的功能点就是支持在线测试，等价于Postman接口测试。就问你们爱了没。

        如下就给大家演示一下，也就是几个api的使用，就搞定啦，是不是感jio很简单呐。

1、配置controller

        首先我们将会用到两个注解@Api 与 @ApiOperation ;具体注解使用及作用我会在下面进行介绍，这里就直接进行上手使用环节。

/**
 * 用户管理分发器
 */
@RestController@RequestMapping("/user")
@Api(tags = "用户管理模块",description = "用户管理模块") //修饰整个类，进行描述
public class UserController {

@Autowired
private UserService userService;
@GetMapping("/get-users")
public List<UserEntity> getUserList() {
    return userService.getUsers();
}}

重启下项目，神奇的一幕发生了。请看下方截图：

我们再来使用@ApiOperation，如下对接口进行描述：

/**
 * 不分页查询db所有用户信息
 */
@GetMapping("/get-users")
@ApiOperation(value = "不分页查询db1所有用户信息",notes = "不分页查询db1所有用户信息")
public List<UserEntity> getUserList() {
    return userService.getUsers();
}

再次重启下项目，请看：

       出现了你刚配置的文字描述，这也就是方便给前端开发进行接口详细描述提醒。

然后你点击下方调试，点击发送，即：

结果返回：

       是不是很有postman的即视感，没错，在线调试也是被集成进去了。无论对自己还是前端开发都及其方便，毕竟测试接口很方便啊，不需要像postman输入完整访问路径等相关接口调用信息，一切操作都变得很简单。有没有？直接发送请求即可。

2、配置entity等参数结构体

我们再来进行一个参数体配置，看看会发生什么？

@Data
@ApiModel(value = "查询用户参数体合集",description = "查询用户参数体合集")public class QueryUserInfoModel {
   
    @ApiModelProperty("性别")
    private String sex;

    @ApiModelProperty("班级名称")
    private String className;

    @ApiModelProperty("用户ids")
    private List<Integer> userIds;
    
}

然后再结合上方所讲到的，对接口进行描述。

/**
 * 根据用户ids等参数联合查询用户信息
 */
@PostMapping("/getUser-by-ids")
@ApiOperation(value = "根据用户ids等参数联合查询用户信息",notes = "根据用户ids等参数联合查询用户信息")
public List<UserInfoVo> getUserById(@RequestBody QueryUserInfoModel model){
    return userMapper.getUsersByIds(model.getUserIds());
}

再次重启项目，我们可以看到对参数体都有了描述；是不是看着很爽。这样就对非开发人员使用也变得很通透了，一看就知道每个参数分别对应什么意思，而不再需要配置额外的文档进行辅助测试了，对前端对测试对非专业人士都很便利，所以赶紧集成到自己的项目中用起来吧。

       至于上方截图涉及到的是否必填一栏，也是来源于@ApiModelProperty 这个 注解，自带是否必填这个属性(required)，属性默认是false不必填，如果你要告诉前端及测试接口人员指定这个参数必须要填写，那你就把required属性设置值为true 即可，即表示该参数必填，如果不填，则肯定是不会通过接口调用的。

例如下方代码演示：表示该性别字段为必填参数。

@ApiModelProperty(value = "性别",required = true)

       如上我就是制定了性别这个字段，你在通过swagger文档进行接口调用的时候，假设没传，你知道会出现什么问题嘛？聪明人都知道，不就提示字段为空，然后接口调用失败了嘛。

具体详情咱们看swagger调用返回：请看如下：

接着我们将性别字段，随便填入一个值，再进行调用，这个时候我们再看。

       可以看到，接口调用成功了，数据查询也返回了。

       很明显是由于你设置了required = true 这个属性触发的提醒效果，不加这个属性，就表示该字段可填可不填。一般都是接口定义好，如果参数必填，就加上该字段，进行提醒相关人员接口调用的时候，这个参数是必填项，不填则无法接口调用咯。基本就是这么个使用情况啦。

       还有很多api如何使用，期待小伙伴们自行探索啦，这里就给大家演示了基本几个常用的，剩下的就靠大家的自觉性与积极性啦。

... ...

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

三、往期热门推荐

文末🔥

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

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

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

avatar
文章
阅读
粉丝