SpringBoot【十三(实战篇)】集成在线接口文档Swagger2

一、前言🔥

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

 

二、如何生成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如何使用，期待小伙伴们自行探索啦，这里就给大家演示了基本几个常用的，剩下的就靠大家的自觉性与积极性啦。