springBoot集成Swagger实现Api接口在线调试

上一节主要讲了SpringBoot集成jpa对mysql数据库进行增删改查操作，写了有五个接口，不管是用postman还是用单元测试对于调试接口都不是很方便，一方面得记住接口地址，一方面还得知道接口的参数格式，在前后端分离的趋势下，如果后端接口变更前端如何第一时间就能发现呢，这时候swagger就应用而生。

swagger出现的目的是为了给SpringMvc的controller实现Api文档的在线生成以及接口的在线调试，这样即使接口发生任何改动和变化，在swagger的可视化界面中都能很快的发现，对于调试接口是十分便利的

springBoot如何快速集成这么一款优秀的框架呢？集成过程也是十分简单的，大概分这么几个步骤。

1、添加Swagger的依赖

在上一节的项目pom.xml文件中最后面追加swagger的依赖，总共有两个依赖包。

swagger依赖代码，依赖完成后，idea右下角会提示导入，点击导入。

<!-- swagger2集成 -->
<dependencies>
        .....
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- swagger2集成 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
</dependencies>

2、编写Swagger的配置文件

在项目com.apgblogs.firstspringboot包下创建一个config的包，这个包主要用来存放一些第三方框架集成需要的配置类，对于配置的一些属性含义会在视频教程中详细说明

package com.apgblogs.firstspringboot.config;

import com.google.common.collect.Sets;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author xiaomianyang
 * @description
 * @date 2019-05-15 00:14
 */
@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .protocols(Sets.newHashSet("http")) //协议，http或https
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.apgblogs.firstspringboot.controller")) //controller扫描路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("RestFul接口定义")
                .version("1.0")
                .description("用于测试RestFul Api")
                .build();
    }
}

3、在UserController中加入Swagger的注解，实现Api接口可视化调试

package com.apgblogs.firstspringboot.controller;

import com.apgblogs.firstspringboot.entity.TUserEntity;
import com.apgblogs.firstspringboot.service.UserServiceImpl;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;

/**
 * @author xiaomianyang
 * @description
 * @date 2019-06-13 15:54
 */
@Api(description = "用户增删改查接口")
@RestController
@RequestMapping("user")
public class UserController {

    @Autowired
    private UserServiceImpl userService;

    /**
     * @description 查询所有用户
     * @author xiaomianyang
     * @date 2019-06-13 16:05
     * @param []
     * @return java.util.List<com.apgblogs.firstspringboot.entity.TUserEntity>
     */
    @ApiOperation(value="获取所有用户信息",notes = "查询所有用户信息")
    @GetMapping
    public List<TUserEntity> getAllUser(){
        return userService.getUserList();
    }

    /**
     * @description 获取单个用户
     * @author xiaomianyang
     * @date 2019-06-13 16:05
     * @param [id]
     * @return com.apgblogs.firstspringboot.entity.TUserEntity
     */
    @ApiOperation(value="获取单个用户信息",notes="通过用户id查询用户信息")
    @ApiImplicitParam(name = "id",value="用户id",required = true,paramType = "path",dataType = "String")
    @GetMapping("{id}")
    public TUserEntity getUser(@PathVariable("id")String id){
        return userService.getUser(id);
    }

    /**
     * @description 创建用户
     * @author xiaomianyang
     * @date 2019-06-13 16:05
     * @param [tUserEntity]
     * @return com.apgblogs.firstspringboot.entity.TUserEntity
     */
    @ApiOperation(value="新增用户",notes = "新增用户")
    @PostMapping
    public TUserEntity insertUser(@RequestBody TUserEntity tUserEntity){
        return userService.insertUser(tUserEntity);
    }

    /**
     * @description 更新用户
     * @author xiaomianyang
     * @date 2019-06-13 16:05
     * @param [tUserEntity]
     * @return com.apgblogs.firstspringboot.entity.TUserEntity
     */
    @ApiOperation(value="更新用户",notes = "修改用户部分信息")
    @PatchMapping
    public TUserEntity updateUser(@RequestBody TUserEntity tUserEntity){
        return userService.updateUser(tUserEntity);
    }

    /**
     * @description 删除用户
     * @author xiaomianyang
     * @date 2019-06-13 16:13
     * @param [id]
     * @return boolean
     */
    @ApiOperation(value="删除用户",notes = "通过id删除用户")
    @ApiImplicitParam(name = "id",value="用户id",required = true,paramType = "path",dataType = "String")
    @DeleteMapping("{id}")
    public boolean deleteUser(@PathVariable("id")String id){
        userService.deleteUser(id);
        return true;
    }
}

启动项目

4、在浏览器访问Swagger的接口可视化地址并调试

swagger访问地址： http://localhost:8881/first/swagger-ui.html ，访问成功后在浏览器中就可以看到如下所示的界面

可以点击其中一个接口进行测试，点击获取所有用户接口

点击Try it out，点击Execute

返回了所有用户数据如下

5、文章源码地址

码云： https://gitee.com/apgblogs/springBootStudy

至此就完成了springBoot对于swagger的集成，只要所有的controller都加入了swaggr的注解就可以轻松实现在线Api文档的生成。