共计 5306 个字符，预计需要花费 14 分钟才能阅读完成。
恩，java 后端开发的痛就是测试接口。以前都是启动我的项目用 postman 复制地址而后再增加参数，如果参数多的话真的是苦楚的经验，这里我要尝试一下 Swagger 了。。。
Swagger 简介
Swagger 是一个标准和残缺的框架，用于生成、形容、调用和可视化 RESTful 格调的 Web 服务。
1. 新建 Spring Boot 我的项目
1.1 pom.xml
<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>com.battcn</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>2.1.5-RELEASE</version>
</dependency>
<dependency>
<groupId>javax.xml.bind</groupId>
<artifactId>jaxb-api</artifactId>
<version>2.3.0</version>
</dependency>1.2 application.yml
server:
# 端口号
port: 8888
servlet:
# 我的项目前缀
context-path: /swagger
spring:
swagger:
enabled: true
# 我的项目题目
title: spring-boot-swagger
# 我的项目阐明
description: 这是一个简略的 Swagger API 演示
# 版本号，本人定义
version: 1.0.0
contact:
# 本人的信息
name: zhouzhaodong
email: xiuaiba@163.com
url: http://www.zhouzhaodong.xyz
# swagger 扫描的根底包，默认：全扫描
# base-package:
# 须要解决的根底 URL 规定，默认：/**
# base-path:
# 须要排除的 URL 规定，默认：空
# exclude-path:
security:
# 是否启用 swagger 登录验证
filter-plugin: true
# 账号
username: zhouzhaodong
# 明码
password: 123456
# 相干谬误阐明
global-response-messages:
GET[0]:
code: 400
message: Bad Request，这个谬误个别状况下为申请参数不对
GET[1]:
code: 404
message: NOT FOUND，这个谬误个别状况下为申请门路不对
GET[2]:
code: 500
message: ERROR，这个谬误个别状况下为程序外部谬误
POST[0]:
code: 400
message: Bad Request，这个谬误个别状况下为申请参数不对
POST[1]:
code: 404
message: NOT FOUND，这个谬误个别状况下为申请门路不对
POST[2]:
code: 500
message: ERROR，这个谬误个别状况下为程序外部谬误 1.3 接口返回实体类
注解阐明：@ApiModel: 用于响应实体类上，用于阐明实体作用
参数：description="形容实体的作用"
@ApiModelProperty: 用在属性上，形容实体类的属性
参数：value="用户名" 形容参数的意义
name="name" 参数的变量名
required=true 参数是否必选 /**
* 接口返回实体类
*
* @author zhouzhaodong
*/
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "接口返回实体类", description = "Common Api Response")
public class ResponseBody<T> implements Serializable {
private static final long serialVersionUID = -8987146499044811408L;
/**
* 返回状态
*/
@ApiModelProperty(value = "返回状态", required = true)
private Integer code;
/**
* 返回信息
*/
@ApiModelProperty(value = "返回信息", required = true)
private String message;
/**
* 返回数据
*/
@ApiModelProperty(value = "返回数据", required = true)
private T data;
}
1.4 新建 Person 实体类
注解阐明：@ApiModel: 用于响应实体类上，用于阐明实体作用
参数：description="形容实体的作用"
@ApiModelProperty: 用在属性上，形容实体类的属性
参数：value="用户名" 形容参数的意义
name="name" 参数的变量名
required=true 参数是否必选 /**
* 用户实体类
*
* @author zhouzhaodong
*/
@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "用户实体", description = "User Entity")
public class Person implements Serializable {
private static final long serialVersionUID = 5057954049311281252L;
/**
* 主键 id
*/
@ApiModelProperty(value = "主键 id", required = true)
private Integer id;
/**
* 用户名
*/
@ApiModelProperty(value = "用户名", required = true)
private String name;
/**
* 工作岗位
*/
@ApiModelProperty(value = "工作岗位", required = true)
private String job;
}1.5 新建 controller
注解阐明：@API: 放在申请的类上, 与 @Controller 并列, 阐明类的作用, 如用户模块, 订单类等.
参数：tags="阐明该类的作用，参数是个数组，能够填多个"
value="该参数没什么意义，在 UI 界面上不显示，所以不必配置"
description = "用户根本信息操作"
@ApiOperation: 用在申请的办法上, 阐明办法的作用。参数：value="办法的用处和作用"
notes="办法的注意事项和备注"
tags：阐明该办法的作用，参数是个数组，能够填多个。格局：tags={"作用 1","作用 2"}
@ApiImplicitParam：用于办法，示意独自的申请参数
参数：name="参数 ming"
value="参数阐明"
dataType="数据类型"
paramType="query" 示意参数放在哪里
· header 申请参数的获取：@RequestHeader
· query 申请参数的获取：@RequestParam
· path（用于 restful 接口）申请参数的获取：@PathVariable
· body（不罕用）· form（不罕用）defaultValue="参数的默认值"
required="true" 示意参数是否必须传
@ApiImplicitParams: 用在申请的办法上，蕴含多 @ApiImplicitParam/**
* 控制器
*
* @author zhouzhaodong
*/
@RestController
@RequestMapping("/person")
@Api(tags = "1.0.0-SNAPSHOT", description = "用户治理", value = "用户治理")
@Slf4j
public class PersonController {
@GetMapping
@ApiOperation(value = "条件查问", notes = "备注")
@ApiImplicitParams({@ApiImplicitParam(name = "name", value = "用户名", dataType = DataType.STRING, paramType = ParamType.QUERY, defaultValue = "xxx")})
public ResponseBody<Person> getByPersonName(String name) {log.info("多个参数用 @ApiImplicitParams");
return ResponseBody.<Person>builder().code(200).message("操作胜利").data(new Person(1, name, "JAVA")).build();}
@GetMapping("/{id}")
@ApiOperation(value = "主键查问", notes = "备注")
@ApiImplicitParams({@ApiImplicitParam(name = "id", value = "用户编号", dataType = DataType.INT, paramType = ParamType.PATH)})
public ResponseBody<Person> get(@PathVariable Integer id) {log.info("单个参数用 @ApiImplicitParam");
return ResponseBody.<Person>builder().code(200).message("操作胜利").data(new Person(id, "u1", "p1")).build();}
@DeleteMapping("/{id}")
@ApiOperation(value = "删除用户", notes = "备注")
@ApiImplicitParam(name = "id", value = "用户编号", dataType = DataType.INT, paramType = ParamType.PATH)
public void delete(@PathVariable Integer id) {log.info("单个参数用 ApiImplicitParam");
}
@PostMapping
@ApiOperation(value = "增加用户", notes = "备注")
public Person post(@RequestBody Person person) {log.info("如果是 POST PUT 这种带 @RequestBody 的能够不必写 @ApiImplicitParam");
return person;
}
@PostMapping("/multipar")
@ApiOperation(value = "增加用户", notes = "备注")
public List<Person> multipar(@RequestBody List<Person> person) {log.info("如果是 POST PUT 这种带 @RequestBody 的能够不必写 @ApiImplicitParam");
return person;
}
@PostMapping("/array")
@ApiOperation(value = "增加用户", notes = "备注")
public Person[] array(@RequestBody Person[] person) {log.info("如果是 POST PUT 这种带 @RequestBody 的能够不必写 @ApiImplicitParam");
return person;
}
@PutMapping("/{id}")
@ApiOperation(value = "批改用户", notes = "备注")
public void put(@PathVariable Long id, @RequestBody Person person) {log.info("如果你不想写 @ApiImplicitParam 那么 swagger 也会应用默认的参数名作为形容信息");
}
}2. 测试
2.1 关上 http://localhost:8888/swagger/swagger-ui.html
++ 留神：++
如果咱们关上页面发现咱们后盾的汉字变成了乱码，须要设置 IDEA 的文件编码
2.2 登录
2.2.1 所有接口
2.2.2 点击某个接口
2.2.3 点击在线调试
2.2.4 点击发送按钮
集体博客地址：
http://www.zhouzhaodong.xyz
GitHub 代码地址：
https://github.com/zhouzhaodo…
正文完
