Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。
作用:
1. 接口的文档在线自动生成。
2. 功能测试。
在做Spring+SpringMVC+Mybatis的项目中整合Springfox(Swagger2)。 在网上查看了很多的资料,遇到了好多坑点,摸索了多半天,总算是成功的整合了。现在记录一下成果,希望能给有需求的朋友提供参考,就可以早点回家吃饭了
今天不讲SSM整合,是在这个基础上整合springfox,我的Spring版本是4.0.9.RELEASE,springfox用的是2.4.0(spring版本要和springfox对应,高版本的springfox里面有些方法低版本的Spring没有,我们工作环境是spring4.0.9,所以为以下示例,但是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是否正常工作
启动项目:能够正常的工作