最近学习SSM发现一个做api测试的小工具,前后端分离的情况下,直接可以生成图形化的API测试界面,不需手动填地址,拼参数,用下来感受良好,分享一下:
1.swagger2的配置
1)在父工程pom文件中添加依赖
在properties标签中添加
<!--swagger2版本支持-->
<swagger2>2.10.5</swagger2>
版本锁定
<!--swagger2 版本锁定-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger2}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger2}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-spring-webmvc</artifactId>
<version>${swagger2}</version>
</dependency>
2)在启动项目的web工程中的pom中引入依赖
在properties标签中添加
<!--swagger2版本支持-->
<swagger2>2.10.5</swagger2>
版本锁定
<!--swagger2 版本锁定-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger2}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger2}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-spring-webmvc</artifactId>
<version>${swagger2}</version>
</dependency>
3)在启动项目的web工程中添加Swagger的配置类
package com.ithaha.travel;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
import java.util.function.Predicate;
@Configuration
//开启swagger2的webmvc支持
@EnableSwagger2WebMvc
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
// 构建API文档 文档类型为swagger2
return new Docket(DocumentationType.SWAGGER_2)
.select()
// 配置 api扫描路径
.apis(RequestHandlerSelectors.basePackage("com.ithaha.travel.web"))
// 指定路径的设置 any代表所有路径
.paths(PathSelectors.any())
// api的基本信息
.build().apiInfo(new ApiInfoBuilder()
// api文档名称
.title("SSM哈哈旅游Swagger接口文档")
// api文档描述
.description("SSM哈哈旅游,描述信息......")
.contact(new Contact("束XX", "http://www.haha.com", "58948528@qq.com"))
// api文档版本
.version("1.0") // 版本
.build());
}
}
4)核心配置类SpringMvcConfig中添加扫描
/**
* @Description:声明spring-mvc的配置类
*/
@ComponentScan(value = {"springfox.documentation.swagger.web"})
@Configuration
public class SpringMvcConfig extends SpringMvcConfig {
/**
* 资源路径 映射
*/
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
/**
* 支持webjars
*/
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
/**
* 支持swagger
*/
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
super.addResourceHandlers(registry);
}
}
好了,配置阶段已完成,接下来可以进行对web层相关类的支持了
2.swagger2支持controller
1)swagger2常用注解
@Api:用在请求的类上,表示对类的说明
tags=“说明该类的作用,可以在UI界面上看到的注解”
value=“该参数没什么意义,在UI界面上也看到,所以不需要配置”
@Api(tags = "用户模块")
public class UserController {
//相关代码
}
@ApiOperation:用在请求的方法上,说明方法的用途、作用
value=“说明方法的用途、作用”
notes=“方法的备注说明”
@GetMapping("/logout")
@ApiOperation(value = "退出",notes ="用户请退出")
public ResponseWrap<Boolean> loginOutUser() throws ProjectException {
//相关代码
}
@ApiImplicitParams:用在请求的方法上,表示一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
name:参数名
value:参数的汉字说明、解释
required:参数是否必须传
paramType:参数放在哪个地方
· header --> 请求参数的获取:@RequestHeader
· query --> 请求参数的获取:@RequestParam
· path(用于restful接口)–> 请求参数的获取:@PathVariable
· div(不常用)
· form(不常用)
dataType:参数类型,默认String,其它值dataType=“Integer”
defaultValue:参数的默认值
@ApiImplicitParams({
@ApiImplicitParam(name="pageNum",value="页码",dataType="string", paramType = "query"),
@ApiImplicitParam(name="pageSize",value="每页条数",dataType="string", paramType = "path")})
public ResponseWrap<PageInfo<RouteVo>> findMyFavorite(@RequestBody FavoriteVo favoriteVo,
@PathVariable("pageNum")Integer pageNum,
@PathVariable("pageSize")Integer pageSize) throws ProjectException {
//相关代码
}
@ApiResponses:用在请求的方法上,表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
@ApiResponses({
@ApiResponse(code=400,message="请求参数没填好"),
@ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")})
public ResponseWrap<PageInfo<RouteVo>> findMyFavorite(@RequestBody FavoriteVo favoriteVo,
@PathVariable("pageNum")Integer pageNum,
@PathVariable("pageSize")Integer pageSize) throws ProjectException {
//相关代码
}
@ApiModel:用于响应类上,表示一个返回响应数据的信息
(这种一般用在post创建的时候,使用@RequestBody这样的场景,
请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:用在属性上,描述响应类的属性
3.启动服务器,访问swagger2的ui页面
关于服务器,本人使用tomcat7
以下结果出现则表示成功(中间会有两个版本的报错,可以忽略不影响结果)
成功后可直接去访问页面啦(因为有其他工具的端口号是8080,本人改了其他端口的;此处端口号对应tomcat端口号)
http://localhost:8080/swagger-ui.html
swagger2的优劣势:
优势:
代码下载下来后加几个配置就可直接进行接口测试,对比其他接口测试工具不需要拼接参数,贴链接,等信息还是比较方便(注解相关可以选择性的加或者不加)
劣势:
目前看下来只能做单接口的测试,无法像postman那样可以多接口串在一起跑,做半自动化
先记录到这里吧,后续有新发现的话再过来更新下。。。