RESTful服务简单了解、构建RESTful应用接口、使用Swagger生成Web API文档

一、RESTful介绍

1、定义

1、RESTful是目前流行的互联网软件服务架构设计风格
2、REST（Representational State Transfer,表述性状态转移）一词是由Roy Thomas Fieding在2000年的博士论文中提出的，它定义了互联网软件服务的架构原则，如果一个架构符合REST原则，则称之为RESTful架构
3、REST并不是一个标准，它更像一组客户端和服务端交互时的架构理念和设计原则，基于这种架构理念和设计原则的Web API更加简洁，更有层次。

2、RESTful特点

1、每一个URL代表一种资源
2、客户端使用GET（用于获取资源）、POST（用于新建资源，也可以用于更新资源）、PUT（更新资源）、DELETE（用于删除资源）四种表示操作方式的动词对服务端资源进行操作。
3、通过操作资源的表现形式来实现服务端请求操作
4、资源的表现形式是JSON或者HTML
5、客户端与服务端之间的交互在请求之间是无状态的，从客户端到服务端的每个请求都包含必需的信息

二、构建RESTful应用接口

1、符合RESTful规范的Web API需要具备如下俩个关键特性：

1、安全性：安全的方法被期望不会产生任何副作用，当我们使用GET操作获取资源时，不会引起资源本身的改变，也不会引起服务器状态的改变
2、幂等性：幂等的方法保证了重复进行一个请求和一次请求的效果相同（并不是指响应总是相同的，而是指服务器上资源的状态从第一次请求后就不再改变），数学上幂等性是指N次变换和一次变换相同

HTTP Method
HTTP对应Web操作

HTTP状态码
1、HTTP状态码就是服务向用户返回的状态码和提示信息，客户端的每一次请求，服务都必须给出回应，回应包括HTTP状态码和数据俩部分。
2、HTTP定义了40个标准状态码，可用于传达客户端请求的结果。状态分以下5个类别：
1xx:信息，通信传输协议级信息
2xx：成功，表示客户端的请求已成功接受
3xx:重定向，表示客户端必须执行一些其他操作才能完成其请求
4xx：客户端错误，此类错误状态码指向客户端
5xx：服务器错误，服务器负责这写错误状态码

2、SpringleBoot实现RESTful

SpringleBoot提供的spring-boot-starter-web组件完全支持开发RESTful API，提供了与RSET操作方式对应的注解

@GetMapping：处理GET请求，获取资源
@PostMapping：处理POST请求，新增资源
@PutMapping：处理PUT请求，更新资源
@DeleteMapping：处理DELETE请求，删除资源
@PatchMapping：处理PATCH请求，用于部分更新资源

在RESTful架构中，每个网址代表一种资源，所以URL中建议不要包含动词，只包含名词即可，而且所用的名词往往与数据库的表格名对应
用户管理模块API示例：

下图案例解析：
1、请求中“{id}”的"{}"表示id是动态变化的，且需要添加@PathVariable注解才能拿到值id

三、使用Swagger生成Web API文档

Swagger简单了解

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务，是非常流行的API表达工具
Swagger能够自动生成完善的RESTful API文档，同时并根据后台代码的修改同步更新，同时提供完整的测试页面来调试API

**使用：**在Spring Boot项目中集成Swagger同样非常简单，只需在项目中引入springfox-swagger2和springfox-swagger-ui依赖即可
在pom.xml里添加如下依赖

关于Spring Boot配置类都需要加上@Configuration 注解

直接运行http://localhost:8080/swagger-ui.html#/

Swagger常用注解
用来描述接口信息

例如：添加@ApiOperation注解