利用Springfox集成Swagger与Springmvc

swagger用于定义API文档，好处：

• 前后端分离开发
• API文档非常明确
• 测试的时候不需要再使用URL输入浏览器的方式来访问Controller
• 传统的输入URL的测试方式对于post请求的传参比较麻烦（当然，可以使用postman这样的浏览器插件）
• springfox基于swagger2，兼容老版本

利用Springfox集成Swagger主要分为两步：

1. Springmvc4集成Springfox

配置文件详解可参考Springfox官方文档，官方文档为英文版，想要快速上手可以参考官方给出的springfox-demo，下面就根据官方文档来进行配置，首先添加Maven依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.2.2</version>
</dependency>

然后创建Swagger配置类SwaggerConfig

package com.lw.swagger;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;

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;

@Configuration //让Spring来加载该类配置
@EnableWebMvc
@EnableSwagger2 //启用Swagger2
@ComponentScan(basePackages = { "com.lw.controller" }) //指定Swagger扫面的包
public class SwaggerConfig {

  /**
   * Every Docket bean is picked up by the swagger-mvc framework - allowing for multiple swagger groups i.e. same code base multiple swagger resource listings.
   */
  @Bean
  public Docket customDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
           .select()            //select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现
           .apis(RequestHandlerSelectors.any()) //扫描指定包内所有Controller定义的Api，并产生文档内容（除了被@ApiIgnore指定的请求）。
           .paths(PathSelectors.any())
           .build()
           .apiInfo(apiInfo()); //用来创建该Api的基本信息（这些基本信息会展现在文档页面中）
  }

  private ApiInfo apiInfo() {
    return new ApiInfoBuilder().title("Spring-mvc中使用Springfox集成Swagger2构建RESTful APIs").build();
  }

}

此时便可通过 访问/api-docs可以看到json数据。

2. Springmvc4集成Swagger-ui

首先添加Maven依赖：

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

由于springfox-swagger-ui采用webjar的方式引入页面，需要在sping xml中配置静态资源访问：

<!-- Enables swgger ui-->
    <mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
    <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>

集成swagger UI之后访问 http://localhost:8080/swagger-ui.html  即可看到swagger界面。
注意：swagger UI基于/api-docs中提供的数据，若设置springfox时没有在/api-docs中添加相关json数据，swagger UI编译验证过程会报错。验证需要引入commons-lang3包，没有的需要添加依赖。

<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.4</version>
</dependency>