学会了Swagger，再也不用PostMan做接口测试了
Posted jiangxiaoju
tags:
篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了学会了Swagger，再也不用PostMan做接口测试了相关的知识，希望对你有一定的参考价值。
说到swagger，你第一反应想到的是什么呢？是不是这首洗脑神曲。
我们说的swagger当时不是这个洗脑神曲了。
swagger是一款API框架，用于开发中接口测试使用的。提供了丰富的注解，方便我们在开发中生成api接口文档以及做接口测试。学会了swagger，再也不需要postman等接口测试工具 了。
文章目录
简介
-
借助Swagger开源和专业工具集，为用户，团队和企业简化API开发。使用Swagger可以帮助您大规模设计和记录API。
-
只要导入项目中，就可以在线访问。
-
可以在线生成Resutful Api文档。
SpringBoot集成Swagger
添加依赖
继承swagger，只需要导入两个依赖作标即可（在此之前，需要先创建一个springboot项目，以及导入web相关依赖，以便之后进行测试使用。）
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
下面是博主测试使用时的依赖包
因为用到了Lombok，所以IDE得装上Lombok插件才能用，否则可以选择移除
<properties>
<java.version>1.8</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<optional>true</optional>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
</dependencies>
运行项目
当你导入好依赖作标后，就已经开始可以使用了。swagger进行了一些默认配置。
访问/swagger-ui.html这个地址即可。
例如是在本地的8080端口运行的话，就访问localhost:8080/swagger-ui.html
出现这么个界面就可以正常使用了。
- A：关于接口文旦的说明介绍
- B：分组信息
- C：项目中需要测试的api接口
- D：模型类
接下来说说改如何修改配置上面提到的4个信息
Swagger配置
swagger配置需要用Docket实例。
1、创建一个SwaggerConfig.java，加上@EnableSwagger2表示开启swagger
package cn.jxj4869.swaggerstart.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig
2、创建Docket实例
@Bean
public Docket docket()
return new Docket(DocumentationType.SWAGGER_2);
构造函数需要传入DocumentationType。通过源码可以看到DocumentationType给我们提供了三个常量，而我们使用的是swagger2。所以就选择SWAGGER_2。
public class DocumentationType extends SimplePluginMetadata
public static final DocumentationType SWAGGER_12 = new DocumentationType("swagger", "1.2");
public static final DocumentationType SWAGGER_2 = new DocumentationType("swagger", "2.0");
public static final DocumentationType SPRING_WEB = new DocumentationType("spring-web", "1.0");
private final MediaType mediaType;
3、通过ApiInfo修改Document也就是A部分（上面那个图）的信息。
@Bean
public Docket docket()
Contact contact = new Contact("jiangxiaoju", "https://blog.csdn.net/qq_43058685", "邮箱");
ApiInfo apiInfo = new ApiInfo(
"Swagger配置", // 标题
"Swagger演示信息", // 描述
"v1.0", // 版本
"https://blog.csdn.net/qq_43058685", // 组织链接
contact, // 联系人信息
"Apach 2.0 许可", // 许可
"许可链接", // 许可连接
new ArrayList<>()// 扩展
);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo);
配置好后重启项目。
4、通过Docket中的select()配置swagger扫描接口的范围。
默认是扫描整个项目中的api接口。所以在C部分才会显示一个basic-error-controller接口。如果我们只需要我们自己项目下的api接口信息。可以通过下面这个配置来实现
@Bean
public Docket docket()
Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
ApiInfo apiInfo = new ApiInfo(
"Swagger学习", // 标题
"学习演示如何配置Swagger", // 描述
"v1.0", // 版本
"http://terms.service.url/组织链接", // 组织链接
contact, // 联系人信息
"Apach 2.0 许可", // 许可
"许可链接", // 许可连接
new ArrayList<>()// 扩展
);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
.select()
.apis(RequestHandlerSelectors.basePackage("cn.jxj4869.swaggerstart"))
.build()
;
RequestHandlerSelectors 可以配置扫描的方式。主要有以下几种
- any：就是扫描所有的接口
- none：所有接口都不扫描
- basePackage：需要传入一个包名，会扫描该包名下所有的接口
除此之外还可以用path对扫描路径进行过滤
@Bean
public Docket docket()
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
.select()
.apis(RequestHandlerSelectors.basePackage("cn.jxj4869.swaggerstart"))
.paths(PathSelectors.ant("/jxj4869/**")) // 扫描以jxj4869开头的接口
.build()
;
5、配置swagger的开关
@Bean
public Docket docket()
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
// 选择是否开启swagger 。true为开启，false为关闭
.enable(true)
.select()
.apis(RequestHandlerSelectors.basePackage("cn.jxj4869.swaggerstart"))
.paths(PathSelectors.ant("/jxj4869/**")) // 扫描以jxj4869开头的接口
.build()
;
6、配置分组信息
当一个项目需要多个人开发时，每个人负责各自实现的接口。这时候就需要他们可以各自写api接口文档。
通过Docket的groupName()方法设置组名
@Bean
public Docket docket()
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
.groupName("组1")
.enable(true)
.select()
.apis(RequestHandlerSelectors.basePackage("cn.jxj4869.swaggerstart"))
.paths(PathSelectors.ant("/jxj4869/**")) // 扫描以jxj4869开头的接口
.build()
;
如果有多个组的话，可以实例化多个Docket放到容器中就行。
常用注解
下面为swagger中常用的注解，具体用法参考后面的说明
| Swagger注解 | 简单说明 |
|---|---|
| @Api(tags = “模块说明”) | 作用在模块类上 |
| @ApiOperation(“接口说明”) | 作用在接口方法上 |
| @ApiModel(“模型类说明”) | 作用在模型类上：如VO、BO |
| @ApiModelProperty( “模型属性说明”) | 作用在类方法和属性上，hidden设置为true可以隐藏该属性 |
| @ApiParam(“接口方法参数说明”) | 作用在参数、方法和字段上，类似@ApiModelProperty |
| @ApiImplicitParam | 类似于@ApiParam，可以作用在类方法上 |
| @ApiImplicitParams | 可以放多个@ApiImplicitParam |
这里说下@ApiParam和@ApiImplicitParam使用时的区别。
- 用@ApiParam备注的参数，参数类型是
application/json。适合用在Post等请求类型上。 - 用@ApiImplicitParam备注的参数，参数类型时query。
所以要在get类型的请求接口上，不要使用@ApiParam
模型注解使用
先定义个user类。
- @Data：Lombok中的注解，用于生成getter和setter
- @Accessors：Lombok中的注解，可以使用链式调用
解析来两个注解就是swagger中的
- @ApiModel：用来给模型添加描述。
- @ApiModelProperty：作用在模型属性上，常用的就是备注属性信息。还有可以其他的可选参数，可以参考源码进行使用，例如显示变量的类型，是否显示该备注等。
package cn.jxj4869.swaggerstart.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.experimental.Accessors;
import java.util.Date;
@ApiModel("用户类")
@Data
@Accessors(chain = true)
public class User
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("密码")
private String password;
@ApiModelProperty("日期")
private Date date;
配置好重启项目后，就可以看到
Api接口的调用
在使用api接口之前，先在controller上，加上一些注解。
package cn.jxj4869.swaggerstart.controller;
import cn.jxj4869.swaggerstart.pojo.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import java.util.Date;
@RestController
@Api("这是一个Hello Controller")
public class HelloController
@GetMapping("/hello")
@ApiOperation("这会返回一个User信息")
@ApiImplicitParams(
@ApiImplicitParam(name = "username",value = "用户名"),
@ApiImplicitParam(name = "password",value = "密码"),
)
public User test(String username, String password)
return new User().setPassword(password).setUsername(username).setDate(new Date());
配置好后，效果如图所示
如果一个方法明确了是使用什么类型的请求，例如上面的代码用了@GetMapping，只能用get请求，所以下面就只显示了一个api接口
但是如果使用了@RequestMapping，但是没有明确指明用哪种类型的请求，会把所有的请求类型接口都列出来
接下来测试使用接口
点击右上角的 try it out后，输入对应的参数。点execute就行可以执行力
上面使用了Get方式的请求，接下来我们来试下Post请求方式
@PostMapping("/hello")
@ApiOperation("这会返回一个User信息")
public User test1(@ApiParam("用户名") String username,@ApiParam("密码") String password)
return new User().setPassword(password).setUsername(username).setDate(new Date());
到此Swagger常用方法也都介绍完了，别忘了留下一键三连再走。
以上是关于学会了Swagger，再也不用PostMan做接口测试了的主要内容，如果未能解决你的问题，请参考以下文章
Spring Boot 集成 Swagger，再也不写接口文档了！