SpringMVC+Swagger2整合（springfox-swagger）

一、前言

Swagger是一款RESTFUL接口文档在线自动生成+功能测试的工具软件。Swagger是一个规范和完整的框架，用于生成、描述、调用和可视RESTFul风格的Web服务
springfox-swagger是用于用Spring构建API的自动JSON API文档的开源工具集合，可以让开发者快速的将swagger集成到项目中。此外如果不单独部署swagger，可以使用springfox-swagger-ui集成到项目中。

二、项目引入依赖

此处我们使用maven进行项目管理，去 https://mvnrepository.com 搜索springfox-swagger，会看到Springfox Swagger2 和 Springfox Swagger Ui，我们使用最新的2.7.0版本，获取对应的pom.xml配置，如下：

注意: spring版本依赖

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

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

启动时会报错，提示找不到 com.fasterxml.jackson.core.jackson-databind，需要加入依赖

<dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-databind</artifactId>
      <version>2.6.6</version>
</dependency>

三、配置

配置部分主要分两部分，第一是Swagger的配置，即项目启动的时候需要读取到相应的配置来加载swagger并扫描形成文档，另外可以根据运行环境来决定是否启用swagger扫描。

1. swagger配置

// WebAppConfig.java
package com.web.swagger2;

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;

import springfox.documentation.builders.ApiInfoBuilder;
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;

@Configuration
@EnableSwagger2
@EnableWebMvc
@ComponentScan(basePackages = {"com.web.api", "com.web.controller"}) // 扫描路径
public class WebAppConfig {
    
    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }
    
    /**
     * 接口描述信息
     * @return
     */
    private ApiInfo apiInfo() {
        Contact contact = new Contact("后台接口", "http://www.test.com", "xxx@123.com");
        return new ApiInfoBuilder()
            .contact(contact)
            .title("系统API接口")
            .description("系统API接口")
            .version("3.0.0")
            .build();
    }
}

2. spring配置

这里需要注意两个地方，首先要支持/v2/api-docs的路径，如果被拦截则不能返回正确的文档json；其次如果项目中做了权限控制，也需要对swagger的相关路径进行放行。

设置web.xml

<servlet-mapping>
    <servlet-name>springServlet</servlet-name>
    <url-pattern>/*</url-pattern>   // 这里需要支持/v2/api-docs路径
  </servlet-mapping>

设置spring-mvc.xml

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

四、控制器以及注解

控制器(@Controller)只要在扫描路径中(@ComponentScan)，不需要任何配置，就已经会被springfox-swagger识别了，下面的例子是简单的控制器。

@Controller
@RequestMapping("/test")
public class TestController {
    @ApiOperation(value="一个测试API",notes = "第一个测试api")
    @ResponseBody
    @RequestMapping(value = "/hello",method = RequestMethod.GET)
    public String hello()
    {
        return "hello";
    }
}

注解请参考 http://springfox.github.io/springfox/javadoc/current/,以下为主要常用的注解：

@ApiIgnore 忽略注解标注的类或者方法，不添加到API文档中
@ApiOperation 展示每个API基本信息

  value api名称
  notes 备注说明

@ApiImplicitParam 用于规定接收参数类型、名称、是否必须等信息

name 对应方法中接收参数名称
value 备注说明
required 是否必须 boolean
paramType 参数类型 body、path、query、header、form中的一种 
body 使用@RequestBody接收数据 POST有效
path 在url中配置{}的参数
query 普通查询参数 例如 ?query=q ,jquery ajax中data设置的值也可以，例如 {query:”q”},springMVC中不需要添加注解接收
header 使用@RequestHeader接收数据
form 笔者未使用，请查看官方API文档
dataType 数据类型，如果类型名称相同，请指定全路径，例如 dataType = “java.util.Date”，springfox会自动根据类型生成模型

@ApiImplicitParams 包含多个@ApiImplicitParam
@ApiModelProperty 对模型中属性添加说明，例如上面的PageInfoBeen、BlogArticleBeen这两个类中使用，只能使用在类中。

 value 参数名称
 required 是否必须 boolean
 hidden 是否隐藏 boolean

@ApiParam 对单独某个参数进行说明，使用在类中或者controller方法中都可以。注解中的属性和上面列出的同名属性作用相同

五、查看文档

项目启动后可以访问 http://localhost:8080/v2/api-docs，这个接口返回json格式的接口文档信息。

访问http://localhost:8080/swagger-ui.html 可以查看文档

由于我直接使用的正式项目做的配置，这里就不做截图了，大家可以自行体验。

如有任何问题和建议，可留言。