什么是RESTful风格?
第一次听到Restful这个词,总会想到它的中文翻译:平静的。当然这里的restful当然不是指这个词,而是REpresentational State Transfer的缩写。在web开发中,有五个常见的method:Get、Post、Put、Patch、Delete,不同的Method是对同一件事情做不同的操作:
REST指的是网络中Client端和Server端的一种呼叫服务形式,通过既定的规则,满足约束条件和原则的应用程序设计就是Restful风格的设计,对资源的操作包括获取、创建、修改和删除资源,这些操作就是依照我们前面所提到的HTTP Method: GET、POST、PUT、PATCH和DELETE。这正好会对应到资料库基本操作CRUD
RESTful风格的出现是为了给前后端提供更加简洁的API接口,而如何创建一份简单高效的API接口也并非一件简单的事情,尤其是当接口众多的时候,就会让接口创建变得十分吃力,Swagger2应运而生,Swagger2既可以减少创建API文档的工作量,同时说明内容又可以整合到代码之中去,让维护文档和修改代码整合为一体,Swagger2还提供了页面测试功能来调试每一个接口。
基于SpringBoot和Swagger2开发RESTful风格的api接口文档
本次实践依旧使用idea,github源码文末自取。首先创建一个SpringBoot项目,在pom.xml中添加相关依赖,主要Swagger2依赖为下面两个:
<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>
2.创建User实体类
因为项目比较简单,实现User类的增删改查API接口,因此全部放在一个文件夹之下,创建User.java
package com.sdxb.restfultest;
public class User {
private Long id;
private String name;
private Integer age;
//此处省略setter and getter
}
3.创建Swagger2配置文件
@Configuration
@EnableSwagger2
public class Swagger2{
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
//创建api基本信息
.apiInfo(apiInfo())
.select()
//指定扫描的包路径,Swagger会扫描包下所有Controller定义的API
.apis(RequestHandlerSelectors.basePackage("com.sdxb.restfultest"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("RestFul Test")
.description("实现User类的增删改查")
.termsOfServiceUrl("NO terms of service")
.contact(new Contact("少掉下巴","https://blog.csdn.net/qq_41973594","[email protected]"))
.version("1.0")
.build();
}
}
其中@Configuration注解使得Spring启动该配置类,@EnableSwagger2启动Swagger2
package com.sdxb.restfultest;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import java.util.*;
@Api(value = "用户信息管理")
@RestController
@RequestMapping(value="/users")
public class UserController {
//创建一个线程安全的map
static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());
//获取User列表
@ApiOperation(value="获取用户列表", notes="")
@RequestMapping(value={""}, method= RequestMethod.GET)
public List<User> getUserList() {
List<User> r = new ArrayList<User>(users.values());
return r;
}
//根据用户id删除用户
@ApiOperation(value = "删除用户",notes = "根据id删除用户")
@ApiImplicitParam(name = "id",value = "输入用户id",required = true,dataType = "Long")
@RequestMapping(value = "/{id}",method = RequestMethod.DELETE)
public String DeleteList(@PathVariable Long id){
users.remove(id);
return "success";
}
//创建用户
@ApiOperation(value="创建用户", notes="根据User对象创建用户")
@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
@RequestMapping(value="", method=RequestMethod.POST)
public String postUser(@RequestBody User user) {
users.put(user.getId(), user);
return "success";
}
//根据用户id获取用户信息
@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
@RequestMapping(value="/{id}", method=RequestMethod.GET)
public User getUser(@PathVariable Long id) {
return users.get(id);
}
//根据指定id更新对象
@ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象,并根据传过来的user信息来更新用户详细信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
})
@RequestMapping(value="/{id}", method=RequestMethod.PUT)
public String putUser(@PathVariable Long id, @RequestBody User user) {
User u = users.get(id);
u.setName(user.getName());
u.setAge(user.getAge());
users.put(id, u);
return "success";
}
}
以上代码乍一看有很多的配置文件,其实实际使用起来很简单,通过@Api、@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。注解各个参数的功能如下:
@Api:用在请求的类上,表示对类的说明
tags="说明该类的作用,可以在UI界面上看到的注解"
value="该参数没什么意义,在UI界面上也看到,所以不需要配置"
@ApiOperation:用在请求的方法上,说明方法的用途、作用
value="说明方法的用途、作用"
notes="方法的备注说明"
@ApiImplicitParams:用在请求的方法上,表示一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
name:参数名
value:参数的汉字说明、解释
required:参数是否必须传
paramType:参数放在哪个地方
· header --> 请求参数的获取:@RequestHeader
· query --> 请求参数的获取:@RequestParam
· path(用于restful接口)--> 请求参数的获取:@PathVariable
· body(不常用)
· form(不常用)
dataType:参数类型,默认String,其它值dataType="Integer"
defaultValue:参数的默认值
@ApiResponses:用在请求的方法上,表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
@ApiModel:用于响应类上,表示一个返回响应数据的信息
(这种一般用在post创建的时候,使用@RequestBody这样的场景,
请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:用在属性上,描述响应类的属性
5.运行项目
完成全部代码之后,启动SpringBoot项目,在浏览器上输入http://localhost:8080/swagger-ui.html,就能看到RESTful API接口界面
点击try it out,出现输入框,在controller中我们设置的输入类型是User,因此需要输入id,name和age:
点击下方的Execute,可以看到返回结果和状态,基本测试方法就是如此,至此,基于SpringBoot和Swagger2开发RESTful风格的api接口文档就创建完成,附上github地址: