Spring Boot（四）： 集成 Swagger2 展现在线接口文档

前后端分离的大趋势下，后端除了要开发，最重要的就是编写API文档了。但是，由于开发任务的不断增加，接口增加过多，这给API的编写造成一定的难度，使得文档整合的越来越杂糅。

所以，Swagger 就是用来解决这一问题的工具。开发人员不用再提供文档，只需要给出一个Swagger 地址，就可以让需要调用到接口的人员在线获取数据，测试接口功能，可以说是非常便利了。

• 增加Swagger2 的依赖

版本选择方面，现在maven在线仓库中，Swagger2.7的版本选择下载较多，而且2.7版本已经出来一年了，稳定性会比较高，所以本文选择2.7版本进行配置

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

• 配置Swagger2 

package pers.hong.demo.config;

import org.springframework.beans.factory.annotation.Autowired;
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;
import java.beans.PersistenceDelegate;

/**
 * @Description:
 * @Auther: hong
 * @Date: 2018/08/20
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket creatApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("pers.hong.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger测试")
                .description("生成的接口如下")
                .version("1.0")
                .build();
    }
}

其中，creatApi()方法是通过new一个Docket构造器来进行Api的配置，apiInfo()就是文档的参数配置，apis()就是指定想要生成的API的路径，apiInfo()方法通过ApiInfoBuilder来配置各项属性，包括标题、描述、版本等。

这样子Swagger的基本配置就OK了，打开localhost:8080/swagger-ui.html就可以看到

如果遇到下面这个弹窗，清除浏览器缓存就行了

• Swagger2 的使用

测试接口类如下

package pers.hong.demo.controller;

import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import pers.hong.demo.config.Result;
import pers.hong.demo.config.ResultGenerator;
import pers.hong.demo.entity.SysUser;
import pers.hong.demo.service.SysUserService;

import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.util.Map;

/**
 * @Description:
 * @Auther: hong
 * @Date: 2018/08/16
 */
@RestController
public class SysUserController {
    @Autowired
    private SysUserService sysUserService;

    @RequestMapping("/")
    public void index( HttpServletResponse response) throws IOException {
        response.sendRedirect("/login.html");
    }

    @ApiOperation(value = "登录接口测试")
    @RequestMapping(value = "/login", method = RequestMethod.POST)
    public Result login(@RequestBody @ApiParam(value = "用户实体类") SysUser sysUser) {
        Result result = ResultGenerator.genFailResult("登录失败");
        if (StringUtils.isEmpty(sysUser.getUserName()) || StringUtils.isEmpty(sysUser.getPassword())) {
            result.setMessage("请填写登录信息！");
        }
        SysUser loginUser = sysUserService.updateTokenAndLogin(sysUser.getUserName(), sysUser.getPassword());
        if (loginUser != null) {
            result = ResultGenerator.genSuccessResult(loginUser);
        }
        return result;
    }
}

进入Swagger页面，点开login接口

输入value，进行测试，就可以看到返回数据和状态码了

以上就是基本的Swagger使用，还有一些注解和方法我没有使用，不过也不难就是了，总的来说，Swagger是一款极易上手的API文档编写工具

demo地址：https://github.com/hong52ni/SpringBoot-Demo-Aggregate