SpringMVC与Springfox(Swagger2)整合，并使用swagger进行测试

原文写的很好，我照着原文弄下直接就可以用了。然后里面的一些小问题我修改了一下，并记录下来主要流程：

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

作用：

1. 接口的文档在线自动生成。

2. 功能测试。

   Spring版本是4.2.1.RELEASE，springfox用的是2.4.0(spring版本要和springfox对应，高版本的springfox里面有些方法低版本的Spring没有，我们工作环境是spring4.2.1，所以为以下示例，但是spring4.3.5+与springfox2.7.0整合也是可以的)，如果使用FastJson的话版本得在1.2.10以上(不然http://localhost:8080/v2/api-docs返回为空)，我用的是1.2.30。

1、在maven的pom文件中引入springfox的依赖

	<!-- swagger -->
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger2</artifactId>
		<version>2.4.0</version>
	</dependency>
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger-ui</artifactId>
		<version>2.4.0</version>
	</dependency>
               <dependency>  
                   <groupId>com.fasterxml.jackson.core</groupId>  
                   <artifactId>jackson-databind</artifactId>  
                   <version>2.6.3</version>  
               </dependency>  
               <!-- FastJson的版本必须在1.2.10以上-->
	<dependency>
		<groupId>com.alibaba</groupId>
		<artifactId>fastjson</artifactId>
		<version>1.2.30</version>
	</dependency>

2、在源码目录下创建一个单独的package，然后创建Swagger2Config.java文件

package com.common;
 
import org.springframework.context.annotation.Bean;
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;
 
@EnableSwagger2
public class Swagger2Config {
	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2)
			.apiInfo(apiInfo())
  			.enable(true)  //是否启用Swagger
			.select()
			.apis(RequestHandlerSelectors.basePackage("com.group.controller")) //扫描的包
			.paths(PathSelectors.any())
			.build();
	}

private ApiInfo apiInfo() {

	return new ApiInfoBuilder()
		.title("xxx测试服务API")
		.description("杭州xx网络科技@API")
		.termsOfServiceUrl("http://xxx.cc/")
		.license("© 2018-chenwei. All rights reserved.")
		.version("1.0")
		.build();
	}
}

3、在springMVC的配置文件中配置swagger

<!--添加swagger2配置-->
<!-- API访问地址：http://ip:port/项目名称/swagger-ui.html -->
<bean class="com.common.Swagger2Config" />
<mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>
<mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>

4、修改web.xml文件中配置所有的请求都经DispatcherServlet处理

<servlet-mapping>
    <servlet-name>SpringMVC</servlet-name>
    <url-pattern>/</url-pattern>
</servlet-mapping>

注意：这个地方必须配置，如果你配置的是*.XXX的形式会出现api-docs访问出错，这就会导致swagger-ui找不到api的有效路径。使swagger无法正常工作

5、controller的swagger注解写法：

启动项目：能够正常的工作

实体添加swagger注解

@ApiModel(value = "学生成绩实体",description = "")
public class StudentScore implements Serializable {

    private static final long serialVersionUID = 9128825689163506207L;

    @ApiModelProperty(value = "主键id")
    private Integer id;

    @ApiModelProperty(value = "考试批次")
    private Integer batchId;

在swagger中可以查看实体

使用swagger进行接口测试（直接就废掉了postman，很方便）

红框就是请求参数，这里输入参数后点击try it out!就可以测试了：

获取swagger文档的json格式

启动工程后访问：http://localhost:8088/项目名称/v2/api-docs

如果是新版本的springfox，页面更加简洁美观了，如下图

本文参考原文：https://blog.csdn.net/qq_22075041/article/details/82855902

另附相关优秀博文

swagger注释API详细说明

Spring-Boot + Swagger2 自动生成API接口文档

使用swagger2markup和asciidoctor生成美观的Restful API文档