一、前言
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 可以查看文档
由于我直接使用的正式项目做的配置，这里就不做截图了，大家可以自行体验。
如有任何问题和建议，可留言。
