Swagger与SpringMVC整合(附源码！！！)

笔者是做系统开发的，主要工作内容是负责给apk端提供后台接口。以前的时候每出一次版本都要整合一次接口文档，而且还时不时的给apk同事解说各个接口的作用和参数类型等。最近工作相对比较轻松，于是想做一个在线接口测试和生成接口文档的工具。百度后发现了swagger这个工具，看网上的评论感觉还不错，就花了几个小时的时间搭建了这套SpringMVC和Swagger结合的项目。经测试，可以自动生成接口文档，而且还可以直接进行接口测试，效果还是相当不错的。以下为项目整合的详细过程。由于我本身的SpringMVC项目是maven项目，所以本文作用于maven环境下。非maven环境可以自行下载jar包进行实现。
废话不多说，直接进入正题。
一、依赖管理
在pom.xml中添加如下jar依赖：
<!-- swagger-springmvc dependencies -->
   <dependency>
       <groupId>com.google.guava</groupId>
       <artifactId>guava</artifactId>
       <version>15.0</version>
   </dependency>
   <dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
       <artifactId>jackson-annotations</artifactId>
       <version>2.4.4</version>
   </dependency>
   <dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
       <artifactId>jackson-databind</artifactId>
       <version>2.4.4</version>
   </dependency>
   <dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
       <artifactId>jackson-core</artifactId>
       <version>2.4.4</version>
   </dependency>
   <dependency>
       <groupId>com.fasterxml</groupId>
       <artifactId>classmate</artifactId>
       <version>1.1.0</version>
   </dependency>

值得注意的是，这里最好将全部依赖添加进去，虽然maven具有依赖传递性，但是少添加的话可能会导致jar包找不到的异常。
二、Swagger配置
自定义一个config类，来配置swagger。代码如下：

import com.mangofactory.swagger.configuration.SpringSwaggerConfig; 
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.plugin.EnableSwagger; 
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin; 
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean; 
import org.springframework.context.annotation.ComponentScan; 
import org.springframework.context.annotation.Configuration; 
import org.springframework.web.servlet.config.annotation.EnableWebMvc; 

@Configuration 
@EnableSwagger 
@EnableWebMvc 
 @ComponentScan(basePackages ={"com.inspur.controller"}) 
public class SwaggerConfig { 
  private SpringSwaggerConfig springSwaggerConfig; 
  @Autowired 
  public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) { this.springSwaggerConfig = springSwaggerConfig; } 

 @Bean 
 public SwaggerSpringMvcPlugin customImplementation() { 
 return new SwaggerSpringMvcPlugin(this.springSwaggerConfig) .apiInfo(apiInfo()) .includePatterns(".*?"); 
 }
private ApiInfo apiInfo() { 
 ApiInfo apiInfo = new ApiInfo( "国网portal接口", "国网portal接口列表，可用于查看和在线 测试", "My Apps API terms of service", "xxx@163.com", "My Apps API Licence Type", "My Apps API License URL"); 
 return apiInfo; 
 }
 }
大家可以看到，在SwaggerConfig 类开始的时候有四个注解，标红的两个注解是负责SpringSwaggerConfig注入的。在网上有另外一种方法来解决SpringSwaggerConfig注入问题，即不添加这两个注解，但在springmvc.xml里面添加这样一行代码
同样可以解决注入问题。但是在我本地项目启动过程中老是报自动装配异常，所以我并没有在xml里面添加这行代码，而是改用注解的方式。@ComponentScan后面的包名是你需要生成文档的controller所在的包。

截止目前，Swagger的依赖和注入问题已解决，剩下的问题就是controller中的一些小问题了。看下面我的controller的相关代码：
@Controller
public class TestSwaggerController {
    @RequestMapping(value="getUserByName", method = RequestMethod.GET)
    @ResponseBody
    @ApiOperation(value = "根据用户名获取用户对象", httpMethod = "GET", response = List.class, notes = "根据用户名获取用户对象")
    public List getUserByName(@ApiParam(required = true, name = "name", value = "用户名") @PathVariable String name) throws Exception{
        TestEntity testEntity=new TestEntity();
        testEntity.setUname("甄嬛传");
        List result = new ArrayList();
        result.add(0, testEntity);
        return result;
    }
}
上面@ApiOperation对方法进行了说明，@ApiParam对参数进行了说明。待项目跑起来之后你会一目了然的~~~
三、Swagger-UI配置
从https://github.com/swagger-api/swagger-ui中下载swagger-ui目录，直接download  zip即可。在src\main\webapp\WEB-INF\下新建swagger文件夹，将下载好的文件解压后，把dist目录下的全部文件复制到swagger文件夹下。修改swagger/index.html文件，默认是从连接http://petstore.swagger.io/v2/swagger.json获取
API 的 JSON，这里需要将url值修改为http://{ip}:{port}/{projectName}/api-docs的形式，{}中的值根据自身情况填写。比如我的url值为：http://localhost:8080/myframe/api-docs。
四、防止拦截静态资源
在springmvc.xml中添加如下代码：
<mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/"/>

防止对静态资源进行拦截处理。
大功告成！将项目添加到tomcat并启动，在浏览器中输入http://localhost:8080/myframe/swagger/index.html(视个人情况而定)，即可看到如下结果。



既可查看接口的参数和注释等，还可以在线测试。快去试试吧！有问题或者见解欢迎在评论区评论。源代码地址：http://download.csdn.net/detail/fanguoddd/9739577。(标题可能不符，下载后运行有收获哦~~~)
最后，打波广告。微信搜索公众号"省钱潮"，公众号微信号：IT20151230   淘宝购物领券，专为你省钱。