SpringBoot整合swagger2生成在线文档（对接口测试和生成接口文档真是太完美了，赶紧用起来吧）
相信各位在公司写API文档数量应该不少，当然如果你还处在自己一个人开发前后台的年代，当我没说，如今为了前后台更好的对接，还是为了以后交接方便，都有要求写API文档。
该demo完整的代码已经上传到github上，如有需要，请自行clone。
https://github.com/jiangheng88/springboot-mybatisplus-swagger
一、描述
首先说一下swagger的两个主要的作用
1.接口的文档在线自动生成。
2.功能测试。
swagger 中每个注解的作用已经在这篇博客中做了详细的介绍。
https://blog.csdn.net/weixin_43610698/article/details/107392550
二、运用
1、添加依赖
<!--管理接口文档的jar 包-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2、添加swagger 的配置类
@Configuration
@EnableSwagger2 //表示开启swagger
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.pathMapping("/")
.select()
.apis(RequestHandlerSelectors.basePackage("com.atguigu.mpdemo1010.controller"))
.paths(PathSelectors.any())
.build().apiInfo(new ApiInfoBuilder()
//题目
.title("SpringBoot整合Swagger")
//描述
.description("SpringBoot整合Swagger，详细信息......")
//版本号
.version("1.0")
.contact(new Contact("邮箱","https://blog.csdn.net/weixin_43610698","hengheng.com"))
.license("博客地址")
.licenseUrl("https://blog.csdn.net/weixin_43610698")
.build());
}
}
这里提供一个配置类，首先通过@EnableSwagger2注解启用Swagger2，然后配置一个Docket Bean，这个Bean中，配置映射路径和要扫描的接口的位置，在apiInfo中，主要配置一下Swagger2文档网站的信息，例如网站的title，网站的描述，联系人的信息，使用的协议等等。
如此，Swagger2就算配置成功了，非常方便。
此时你的启动项目，输入http://localhost:8080/swagger-ui.html，能够看到如下页面，说明已经配置成功了：
这里要注意，上面的端口号是你项目的端口号，不是固定的8080，这一点一定要注意
http://localhost:8080/swagger-ui.html 就是打开swagger 可视化页面的路径。
特别要注意：8080 端口号不是固定，而是你项目的端口号，你项目的端口号是多少，路径的端口号就是多少，我的项目端口号是8080，所以这里就是8080了
3、生成对应的实体类（这里使用了mybatis-plus的逆向生成代码的工具，在下篇博客会做介绍）
//这里使用lombok这个依赖，可以不用写set、get等方法，直接使用@Data注解就可以
/**
*这里顺便介绍一下lombok吧，使用它很简单
* 第一步，引入依赖
org.projectlombok
lombok
*第二步 在idea 中 下载 lombok 插件
* 第三步 在实体类上添加@Data 这样就可以使用了，极大地简化了实体类
*/
@Data
@EqualsAndHashCode(callSuper = false)
@Accessors(chain = true)
@ApiModel(value = "User对象", description = "")
public class User implements Serializable {
private static final long serialVersionUID = 1L;
@ApiModelProperty(value = "主键ID")
@TableId(value = "id", type = IdType.AUTO)
private Long id;
@ApiModelProperty(value = "姓名")
private String name;
@ApiModelProperty(value = "年龄")
private Integer age;
@ApiModelProperty(value = "邮箱")
private String email;
}
4、mapper 层，service层这里都写到一块吧（很简单，都是调用mybatis-plus内部的api，在下一篇博客中我会介绍mybatis-plus 的使用）
@Repository
public interface UserMapper extends BaseMapper<User> {
}
public interface UserService extends IService<User> {
}
@Service
public class UserServiceImpl extends ServiceImpl<UserMapper, User> implements UserService {
/**
* @return
* @Date 2020/7/16 13:57
* @Author jiangheng
* @Description //TODO 根据id 查询一条记录
**/
@Override
public User getById(Serializable id) {
return super.getById(id);
}
@Override
public List<User> list(Wrapper<User> queryWrapper) {
return super.list(queryWrapper);
}
@Override
public boolean save(User entity) {
return super.save(entity);
}
/**
* @return
* @Date 2020/7/16 16:21
* @Author jiangheng
* @Description //TODO 修改用户信息
**/
@Override
public boolean updateById(User entity) {
return super.updateById(entity);
}
/**
* @return
* @Date 2020/7/16 16:34
* @Author jiangheng
* @Description //TODO 根据id 删除用户信息
**/
@Override
public boolean removeById(Serializable id) {
return super.removeById(id);
}
}
5、controller层，restful Api 接口（重点,包括一整套增删改查）
swagger 中每个注解的作用已经在这篇博客中做了详细的介绍。
https://blog.csdn.net/weixin_43610698/article/details/107392550
@RestController
@RequestMapping("/mpdemo1010/user")
@Api(tags = "用户管理接口")
public class UserController {
@Resource
private UserService userService;
/**
* @return
* @Date 2020/7/16 14:21
* @Author jiangheng
* @Description //TODO 根据id 查询 一条记录
**/
@ApiOperation(value = "根据id查询用户信息")
@GetMapping("selectOneById/{id}")
@ApiImplicitParam(name = "id", value = "用户id", required = true)
public ResultMap selectOne(@PathVariable(value = "id") Integer id) {
User user = userService.getById(id);
if (user != null) {
return ResultMap.success("查询成功", user);
} else {
return ResultMap.error("没有数据");
}
}
/**
* @return
* @Date 2020/7/16 15:33
* @Author jiangheng
* @Description //TODO 查询所有的用户信息
**/
@GetMapping("selectAll")
@ApiOperation(value = "查询所有的用户信息")
public ResultMap selectAll() {
List<User> users = userService.list(null);
if (users != null && users.size() > 0) {
return ResultMap.success("查询成功", users);
} else {
return ResultMap.error("没有数据");
}
}
/**
* @return
* @Date 2020/7/16 15:45
* @Author jiangheng
* @Description //TODO 添加用户
**/
@PostMapping("/insert")
@ApiOperation(value = "添加用户")
@ApiImplicitParam(name = "user", value = "添加的用户信息", required = true)
public ResultMap insert(@RequestBody User user) {
boolean flag = userService.save(user);
if (flag) {
return ResultMap.success("添加成功");
} else {
return ResultMap.error("添加失败");
}
}
/**
* @return
* @Date 2020/7/16 16:15
* @Author jiangheng
* @Description //TODO 根据id修改用户的信息
**/
@PutMapping("update/{id}")
@ApiOperation(value = "更新用户信息", notes = "根据用户id修改用户信息")
@ApiImplicitParams({
@ApiImplicitParam(name="id",value = "用户id",required = true),
@ApiImplicitParam(name = "user",value = "用户信息")
})
public ResultMap update(@PathVariable("id") Integer id,@RequestBody User user){
User user1 = userService.getById(id);
user.setId(user1.getId());
boolean flag = userService.updateById(user);
if(flag){
return ResultMap.success("更新成功");
}
return ResultMap.error("更新失败");
}
/**
* @return
* @Date 2020/7/16 16:28
* @Author jiangheng
* @Description //TODO 根据id 删除用户信息
**/
@DeleteMapping("delete/{id}")
@ApiOperation(value = "删除用户信息")
@ApiImplicitParam(name = "id", value = "用户id", required = true)
public ResultMap delete(@PathVariable("id") long id){
boolean flag = userService.removeById(id);
if(flag){
return ResultMap.success("删除成功");
}
return ResultMap.error("更新失败");
}
}
上面代码就是SpringBoot整合swagger2的全部代码，下面的图片是你看的效果，你可以在上面测试，还有在线文档生成。
三、演示测试过程
这里演示一个比较难得，添加用户信息
!](https://img-blog.csdnimg.cn/20200716201356618.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MzYxMDY5OA==,size_16,color_FFFFFF,t_70)
测试结果
