目录
  1. 1. 前言
  2. 2. restful风格接口
  3. 3. swagger接口文档
  4. 4. 结尾语
谈谈restful风格API编写和接口调用

前言

前后端分离开发已成为主流,专业人做专业事,明确各自的分工有利于提高工作效率。然而实际开发过程中,却受到一些因素的影响。比如接口代码不规范、后端接口不自测、前端传参错误、后端返参问题等等,往往耗费了大量的时间在接口联调上,导致工作效率比较低下。有没有好的方式去提高效率呢,下面就来说说编写restful风格API和swagger接口调用

restful风格接口

简介
Restful风格API是一种软件架构、设计风格,不是标准,只提供一组设计原则和约束条件。用于客户端与服务器进行交互。基于该风格设计的软件可以更简洁,更有层次,更易于实现缓存等机制。
在 Restful 风格中,用户请求的url使用同一个url而用请求方式:get、post、delete、put方式对请求的处理方法进行区分,这样可以在前后台分离式的开发中使得前端开发人员不会对请求的资源地址产生混淆和大量的检查方法名的麻烦,形成一个统一的接口。
非Restful风格弊端
1、大量方法名,多个开发项目命名混乱
2、GET和POST请求方法使用混乱,有些方法不声明具体方式,有时请求会报错
3、不够简洁,每个接口都需要命名且不能复用

实现方式
SpringMVC 的 resturl 是通过 @RequestMapping 及 @PathVariable annotation 提供的,通过如 @RequestMapping(value=”/blog /{id}”,method=RequestMethod.DELETE) 即可处理 /blog/1 的 delete 请求。

GET(查询):从服务器查询,可以在服务器通过请求的参数区分查询的 方式。
POST(创建):在服务器端新建一个资源,调用 insert 操作。
PUT(更新):在服务器端更新资源,调用 update 操作。
PATCH(更新):在服务器端更新资源(客户端提供改变的属性),很少使用
DELETE(删除):从服务器端删除资源,调用 delete 语句。

示例代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
@RestController
@RequestMapping("/web/sysUser")
public class SysUserController extends BaseController {
@Autowired
private SysUserService sysUserService;
@ApiOperation("分页查询")
@GetMapping("/page")
public ResultDto page(SysUserDTO sysUserDTO) {
return sysUserService.querySysUserListByPage(sysUserDTO, PageUtil.buildPageDomain());
}
@ApiOperation("新增")
@PostMapping
public ResultDto add(@Validated @RequestBody SysUserDTO sysUserDTO) {
sysUserService.saveSysUser(sysUserDTO);
return success();
}
@ApiOperation("修改")
@PutMapping
public ResultDto update(@Validated @RequestBody SysUserDTO sysUserDTO){
sysUserService.updateSysUser(sysUserDTO);
return success();
}
@ApiOperation("批量删除")
@DeleteMapping("/{ids}")
public ResultDto delete(@PathVariable Long[] ids){
sysUserService.deleteSysUserByIds(ids);
return success();
}
@ApiOperation("根据id查询单条数据")
@GetMapping("/{id}")
public ResultDto getSysUser(@PathVariable Long id){
SysUserDTO sysUserDTO = sysUserService.querySysUserById(id);
return success(sysUserDTO);
}
}

入参示例
GET请求

1
http://localhost:9000/portal-web/web/sysDictData/list?dictType=sys_user_sex

POST/PUT请求

1
2
3
4
5
6
7
8
9
10
11
12
http://localhost:9000/portal-web/web/sysDictData
{
“creator”: “admin”,
“dictCode”: 0,
“dictLabel”: “男”,
“dictSort”: 1,
“dictType”: “sys_sex”,
“dictValue”: “F”,
“isDefault”: “Y”,
“remark”: “string”,
“status”: “Y”,
}

DELETE请求

1
http://localhost:9000/portal-web/web/sysDictData/1,2

swagger接口文档

简介
swagger接口文档由后端集成,可自定义扫描的接口类,能生成浏览器可直接访问的接口文档,接口名称、入参、回参一目了然,前提是后端添加相关注解,既方便自己接口调试,也方便前端调用接口,本文重点介绍swagger实用的注解,至于集成方法可自行百度

注解

用于controller类上
@Api:对请求类的说明tags
属性:说明该类的作用

1
2
3
4
5
@Api(tags="订单模块")
@Controller
public class OrderController {

}

用于方法上面
@ApiOperation:方法说明
value:说明方法的作用(可省略)
@ApiImplicitParams、@ApiImplicitParam:方法参数说明@ApiImplicitParam用于指定单个参数的说明
name:参数名
value:参数说明
required:参数是否必填
dataType:参数类型
defaultValue:参数默认值

1
2
3
4
5
6
7
8
9
10
11
12
@ApiOperation(value="用户登录")
@ApiImplicitParams({
@ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})
@PostMapping("/login")
public JsonResult login(@RequestParam String mobile, @RequestParam String password,
@RequestParam Integer age){
//...
return JsonResult.ok(map);
}

对象类
@ApiModel:用在JavaBean类上,说明JavaBean的 用途
@ApiModelProperty:用在JavaBean类的属性上面,说明此属性的的含议
value:字段说明
name:重写属性名字
dataType:重写属性类型
required:是否必填
example:举例说明
hidden:隐藏

1
2
3
4
5
6
7
8
9
10
11
@ApiModel(description = "用户登录")
@Data
public class UserLoginVO implements Serializable {
private static final long serialVersionUID = 1L;
@ApiModelProperty(value = "用户名",required=true,example = "张三",dataType = "String")
private String username;
@ApiModelProperty(value = "密码",required=true)
private String password;
@ApiModelProperty(value = "性别",required=true,allowableValues = "F,M")
private String gender;
}

结尾语

restful风格API可通过注解明确CRUD使用的方法,约定数据传输格式,减少接口命名。swagger在线文档可使用相关注解明确接口作用及入参示例,便于自测与联调。实际开发过程中,可以加快接口联调速度,提升工作效率。

文章作者: 微光
文章链接: http://www.guduke.cn/2021/02/08/restful/
版权声明: 本博客所有文章除特别声明外,均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来自 微光
打赏
  • 微信
  • 支付宝

评论