原文写的很好,我照着原文弄下直接就可以用了。然后里面的一些小问题我修改了一下,并记录下来主要流程:
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。
作用:
-
接口的文档在线自动生成。
-
功能测试。
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