REST 是一种很笼统的概念，它代表一种架构风格。
加上版本号
http://localhost:8080/api/v1/list
一旦api接口确定，不在改变接口实现的业务逻辑
资源路径
URI 不能包含动词，只能是名词。注意的是，形容词也是可以使用的，但是尽量少用。一般来说，不论资源是单个还是多个，API 的名词要以复数进行命名。此外，命名名词的时候，要使用小写、数字及下划线来区分多个单词。这样的设计是为了与 json 对象及属性的命名方案保持一致
【GET】 /v1/tags/{tag_id}
有的时候，当一个资源变化难以使用标准的 RESTful API 来命名，可以考虑使用一些特殊的 actions 命名。
【PUT】 /v1/users/{user_id}/password/actions/modify // 密码修改
请求方式
可以通过 GET、 POST、 PUT、 PATCH、 DELETE 等方式对服务端的资源进行操作。其中：
- GET：用于查询资源
- POST：用于创建资源
- PUT：用于更新服务端的资源的全部信息
- PATCH：用于更新服务端的资源的部分信息
- DELETE：用于删除服务端的资源。
响应参数
如果是单条数据，则返回一个对象的 JSON 字符串。
{
"id" : "01234567-89ab-cdef-0123-456789abcdef",
"name" : "example",
"created_time": 1496676420000,
"updated_time": 1496676420000,
...
}
如果是列表数据，则返回一个封装的结构体
{
"count":100,
"items":[
{
"id" : "01234567-89ab-cdef-0123-456789abcdef",
"name" : "example",
"created_time": 1496676420000,
"updated_time": 1496676420000,
...
},
...
]
}
SpringMVC处理Put或Delete
1、首先在web.xml中配置过滤器
<filter>
<filter-name>HiddenHttpMethodFilter</filter-name>
<filter-class>org.springframework.web.filter.HiddenHttpMethodFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>HiddenHttpMethodFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
2、form表单配置隐藏域，注意表单中method必须为post，隐藏域中name和value属性如下所示
<form action="/delete" method="post">
<input name="_method" value="DELETE" type="hidden">
<input type="submit" value="提交">
</form>
3、处理请求
需要加上@ResponseBody注解，否则报错，加上该注解后，就不能返回视图了
@RequestMapping(value = "/delete",method = RequestMethod.DELETE)
@ResponseBody
public String delete() throws IOException {
return "delete";
}
Rest 风格 URL
左边是传统的api，右边是Rest风格的api
/get?id=1 ---->/order/1 get
/add ---->/order post
/delete?id=1 --->/order/1 delete
/update?id=1 --->/order/2 put
SpringBoot处理Put或Delete
1、配置 HiddenHttpMethodFilter（不需要了，SpringBoot已经配置好了）
2、form表单配置隐藏域
<form action="/delete" method="post">
<input name="_method" value="DELETE" type="hidden">
<input type="submit" value="提交">
</form>
接口开发规范
Api请求及响应规范
为了严格按照接口进行开发，提高效率，对请求及响应格式进行规范化。
- 1、get 请求时，采用key/value格式请求，SpringMVC可采用基本类型的变量接收，也可以采用对象接收。
- 2、Post请求时，可以提交form表单数据（application/x-www-form-urlencoded）和Json数据（Content-Type=application/json），文件等多部件类型（multipart/form-data）三种数据格式，SpringMVC接收Json数据使用@RequestBody注解解析请求的json数据。
- 4、响应结果统一信息为：是否成功、操作代码、提示信息及自定义数据。
- 5、响应结果统一格式为json。
示例
@Data
@ToString
public class QueryResponseResult extends ResponseResult {
QueryResult queryResult;
public QueryResponseResult(ResultCode resultCode, QueryResult queryResult) {
super(resultCode);
this.queryResult = queryResult;
}
}
@Data
@ToString
@NoArgsConstructor
public class ResponseResult implements Response {
//操作是否成功
boolean success = SUCCESS;
//操作代码
int code = SUCCESS_CODE;
//提示信息
String message;
public ResponseResult(ResultCode resultCode){
this.success = resultCode.success();
this.code = resultCode.code();
this.message = resultCode.message();
}
public static ResponseResult SUCCESS(){
return new ResponseResult(CommonCode.SUCCESS);
}
public static ResponseResult FAIL(){
return new ResponseResult(CommonCode.FAIL);
}
}
public interface Response {
public static final boolean SUCCESS = true;
public static final int SUCCESS_CODE = 10000;
}
接口文档的编写
Swagger是全球最大的OpenAPl规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发。（https://swagger.io/）
Swagger常用注解（给前端测试用户提示信息的）
在Java类中添加Swagger的注解即可生成Swagger接口，常用Swagger注解如下：
- @Api：修饰整个类，描述Controller的作用
- @ApiOperation：描述一个类的一个方法，或者说一个接口
- @ApiParam：单个参数描述
- @ApiModel：用对象来接收参数
- @ApiModelProperty：用对象接收参数时，描述对象的一个字段 @ApiResponse：HTTP响应其中1个描述 @ApiResponses：HTTP响应整体描述 @ApiIgnore：使用该注解忽略这个API @ApiError ：发生错误返回的信息 @ApiImplicitParam：一个请求参数
- @ApiImplicitParams：多个请求参数
使用
@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：用在属性上，描述响应类的属性
spring boot配置
配置
@Configuration
@EnableSwagger2 //注解表示会去com.xuecheng包下找到所有添加了@RestController注解的类，为这个类中的每一个方法生成接口文档
public class Swagger2Configuration {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.xuecheng"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("学成网api文档")
.description("学成网api文档")
// .termsOfServiceUrl("/")
.version("1.0")
.build();
}
}
给接口文档添加注释信息
@Api(value="cms页面管理接口",description = "cms页面管理接口，提供页面的增、删、改、查")
public interface CmsPageControllerApi {
//页面查询
@ApiOperation("分页查询页面列表")
@ApiImplicitParams({@ApiImplicitParam(name="page",value = "页码",required=true,paramType="path",dataType="int"), @ApiImplicitParam(name="size",value = "每页记录数",required=true,paramType="path",dataType="int")})
public QueryResponseResult findList(int page, int size, QueryPageRequest queryPageRequest);
}
测试：启动spring boot，访问：http://localhost:31001/swagger-ui.html，效果如图
