Springboot中使用Swagger2自动生成文档

一、什么是Swagger2？
它是Api接口文档生成工具，它可以动态生成Api接口文档。它里面有一些常用的注解，比如方法的描述，方法参数的描述都可以通过对应的注解来实现。
 二、Springboot中如何使用Swagger2来自动生成注释文档？
1、添加依赖

<!--接口生成文档swagger2-->
<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>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

2、编写swagger2的配置类

/**
 *通过@Configuration注解，让Spring来加载该类配置，
 * @EnableSwagger2注解来启用Swagger2。
 * 再通过createRestApi函数创建Docket的Bean之后，
 * apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。
 * select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，
 * 本例采用指定扫描的包路径来定义，
 * Swagger会扫描该包下所有Controller定义的API，
 * 并产生文档内容（除了被@ApiIgnore注解的API）。
 */
@EnableSwagger2
@Configuration
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//用来创建该Api的基本信息
                .select()//select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现
                //为当前包路径,所有Controller所在的包路径
                .apis(RequestHandlerSelectors.basePackage("com.gw.production.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    //构建 api文档的详细信息函数
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("Spring Boot 测试使用 Swagger2 构建RESTful API")
                //创建人
                .contact(new Contact("Ricky", "http://www.bytebeats.com", "ricky_feng@163.com"))
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
}

3、编写Controller

/**
 * 这里开始编写自己的RESTful Controller，跟正常开发没什么区别。
 * 主要是接口方法上面新增了几个注解：
 * <p>
 * 通过@ApiOperation注解来给API增加说明
 * 通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明
 * 通过@ApiIgnore来忽略那些不想让生成RESTful API文档的接口
 */
@RestController
@RequestMapping("/demo")
public class TestSwaggerController {
    @ApiIgnore
    @ApiOperation(value = "删除指定id用户", notes = "根据id来删除用户信息")
    @ApiImplicitParam(name = "id", value = "用户id", dataType = "java.lang.Long", paramType = "path")
    @RequestMapping(value = "/user/{id}", method = RequestMethod.DELETE)
    public String delete(@PathVariable Long id) {
        System.out.println("delete user:" + id);
        return "OK";
    }
}

4、如何查看生成的API文档
Springboot启动项目之后，通过浏览器访问下面的路径可以查看文档
http://localhost:8088/operation-production/swagger-ui.html
但是浏览之后会发现，该页面出现404。分析了一下原因，是因为在该项目中根本就没有生成一个叫swagger-ui.html的页面，那该如何解决呢？
由于在之前的开发中，我添加了拦截器，对项目中所有的文件都进行了拦截，所以，需要重写addResourceHandlers() 防止静态资源被 dispatcherServlet拦截，所以，在拦截器中加入下面的代码：

  //添加资源文件，添加Swagger2
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        log.info("添加资源文件成功");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        super.addResourceHandlers(registry);
    }

添加成功之后，我们再次使用浏览器访问http://localhost:8088/operation-production/swagger-ui.html，发现404的问题解决了，通过调试发现，该界面却在拦截器中被拦截了，没有办法返回，所以需要在拦截器中添加免拦截，将拦截器的拦截路径去除下面四个即可。

"/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**"

访问成功了。