Spring Boot进阶1 - 整合Swagger2自动生成RESTful API文档

本文将介绍RESTful API可视化调试工具Swagger2，它可以轻松的整合到spring生态链中，并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量，同时又将说明内容整合入实现代码中，让维护文档和修改代码整合为一体，方便让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API，具体效果如下图所示：

Spring Boot整合Swagger2

1、添加Swagger2依赖

在pom.xml中加入Swagger2的依赖

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

2、编写Swagger2配置类

类名随意，但需要增加@EnableSwagger2和@Configuration注解，如下：

package cn.no7player.config;

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * 
 * ClassName: Swagger2Config <br/>
 * Function: TODO ADD FUNCTION. <br/>
 * Reason: TODO ADD REASON(可选). <br/>
 * date: 2017年4月13日 下午5:19:22 <br/>
 *
 * @author lichch
 * @version
 * @since JDK 1.7
 */
@EnableSwagger2
@Configuration
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                // 为当前包路径cn.no7player.controller
                .apis(RequestHandlerSelectors.basePackage("cn.no7player.controller")).paths(PathSelectors.any())
                .build();
    }

    // 构建 api文档的详细信息函数
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 页面标题
                .title("Spring Boot 测试使用 Swagger2 构建RESTful API")
                // 创建人
                .contact(new Contact("lichch", "https://github.com/lichch/stringboot-mybatis/tree/master",
                        "liCC_liCC@163.com@163.com"))
                // 版本号
                .version("1.0")
                // 描述
                .description("API 描述").build();
    }
}

通过@Configuration注解，让Spring来加载该类配置，@EnableSwagger2注解来启用Swagger2。

再通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore注解的API）。

3、编写Controller

这里开始编写自己的RESTful Controller，跟正常开发没什么区别。主要是接口方法上面新增了几个注解：

通过@ApiOperation注解来给API增加说明
通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明
通过@ApiIgnore来忽略那些不想让生成RESTful API文档的接口

编写SwaggerController

package cn.no7player.controller;

import java.util.ArrayList;
import java.util.List;

import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import com.wordnik.swagger.annotations.ApiOperation;

import cn.no7player.model.User;

/**
 * 
 * ClassName: SwaggerController <br/>
 * Function: TODO ADD FUNCTION. <br/>
 * Reason: TODO ADD REASON(可选). <br/>
 * date: 2017年4月13日 下午2:21:00 <br/>
 *
 * @author lichch
 * @version
 * @since JDK 1.7
 */
@RestController
@RequestMapping(value = "/users")
public class SwaggerController {

    /*
     * http://localhost:8080/swagger-ui.html#/
     */

    /**
     *
     * @return
     */
    @ApiOperation(value = "查询所有用户", notes = "查询得到所有用户")
    @RequestMapping(method = RequestMethod.GET)
    public List<User> getUsers() {
        List<User> list = new ArrayList<User>();

        User user = new User();
        user.setName("hello");
        list.add(user);

        User user2 = new User();
        user.setName("world");
        list.add(user2);
        return list;
    }

    @ApiOperation(value = "通过id查询用户", notes = "通过id查询用户")
    @RequestMapping(value = "/{name}", method = RequestMethod.GET)
    public User getUserById(@PathVariable String name) {
        User user = new User();
        user.setName("hello world");
        return user;
    }
}

完成上述代码后，打包Spring Boot程序并启动，打开浏览器访问：http://localhost:8080/swagger-ui.html，就能看到前文所展示的RESTful API的页面。

4，调试

然后我们可以对请求进行调试，是否符合RESTful请求规范，结果如图

按照如图操作，点击对应的controller 可以查看所有的请求方法和默认结果，并可以找到对应的方法进行测试 如下图

源码下载

https://github.com/lichch/stringboot-mybatis.git