笔者是做系统开发的，主要工作内容是负责给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", "[email protected]", "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。(标题可能不符，下载后运行有收获哦~~~)

没有下载积分的童鞋看这里！！！扫描公众号二维码免费获取。公众号二维码：

                                        

最后，打波广告。微信搜索公众号"购即省"，淘宝购物领券，购物即省钱。