第3天：RESTful服务+Swagger

RESTful介绍

概要介绍

RESTful是目前流行的互联网软件服务架构设计风格。REST（Representational State Transfer，表述性状态转移）定义了互联网软件服务的架构原则，如果一个架构符合REST原则，则称之为RESTful架构。
RESTful并不是一个标准，更像一组客户端和服务端交互时的架构理念和设计原则，基于这种架构理念和设计原则的Web API更加简洁，更有层次，可读性更强。

RESTful的特点

• 每一个URI（每一个链接）代表一种资源。
• 客户端使用GET、POST、PUT、DELETE四种表示操作方式的动词对服务端资源进行操作：GET用于获取资源，POST用于新建资源（也可用于更新资源），PUT用于更新资源，DELETE用于删除资源。（RESTful提倡用不同的请求方式表示不同的操作，可读性更强）
• 通过操作资源的表现形式（即上述的请求方法）来实现对服务器端各种各样的请求操作。
• 资源的表现形式是JSON或者HTML。
• 客户端与服务端之间的交互在请求之间是无状态的，从客户端到服务端的每个请求都包含必需的信息。

RESTful API

符合RESTful规范的Web API需要具备如下两个关键特性：
安全性：安全的方法被期待不会产生任何副作用，当我们使用GET操作获取资源时，不会引起资源本身的改变，也不会引起服务器状态的改变。
幂等性：幂等的方法保证了重复进行一个请求和一次请求的效果相同（并不是指响应总是相同，而是指服务器上资源的状态从第一次请求后就不再改变），在数学上幂等性是指N次变换和一次変换相同。

HTTP Method

HTTP提供了GET、POST、PUT、DELETE等操作类型对某个Web资源进行Create、Read、Update和Delete操作。
一个HTTP请求除了利用URI标志目标资源外，还需要通过HTTP Method指定针对该资源的操作类型，一些常见的HTTP方法及其在RESTful风格下的使用：

HTTP状态码

HTTP状态码就是服务器向用户返回的状态码和提示信息，客户端的每一次请求，服务器都必须给出回应，回应包括HTTP状态码和数据两部分。
HTTP定义了40个标准状态码，可用于传达客户端请求的结果。状态码分为以下5个类别：

• 1xx：信息，通信传输协议级信息
• 2xx：成功，表示客户端的请求已成功接受
• 3xx：重定向，表示客户端必须执行一些其他操作才能完成其请求
• 4xx：客户端错误，此类错误状态码指向客户端
• 5xx：服务器错误，服务器负责这些错误状态码

RESTful API中使用HTTP状态码来表示请求执行结果的状态，适用于RESTful API设计的代码以及对应的HTTP方法。

SpringBoot实现RESTful API

SpringBoot提供的spring-boot-starter-web组件完全支持开发RESTful API，提供了与REST操作方式（GET、POST、PUT、DELETE）对应的注解（当然也可以使用RequestMapping来实现）。

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

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

使用场景示例：

删除用户：
传统设计方案：get http://localhost/del?id=10
REST设计方案：delete http://localhost/user/10 （路径是动态变化的）

代码示例：

@RestController
public class UserController {

    @GetMapping("/user/{id}")
    public String getUserById(@PathVariable int id){
        System.out.println(id);
        return "根据ID获取用户信息";
    }

    @PostMapping("/user")
    public String save(User user){
        return "添加用户";
    }

    @PutMapping("/user")
    public String update(User user){
        return "更新用户";
    }

    @DeleteMapping("/user/{id}")
    public String deleteById(@PathVariable int id){
        System.out.println(id);
        return "根据ID删除用户";
    }
}

构建RESTful应用接口

使用Swagger生成Web API文档

什么是Swagger

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

使用Swagger生成Web API文档

添加依赖
在SpringBoot项目中集成Swagger非常简单，只需在项目中引入springfox-swagger2和springfox-swagger-ui依赖即可。

<!--        添加Swagger2相关功能-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
<!--        添加Swagger-ui相关功能-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

添加配置类SwaggerConfig.java

@Configuration    //告诉Spring容器，这个类是一个配置类
@EnableSwagger2   //启用Swagger2功能
public class SwaggerConfig {
    //配置Swagger2相关的bean
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com"))   //com包下所有的API都交给Swagger2管理
                .paths(PathSelectors.any()).build();
    }

    //API文档页面显示信息
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("演示项目API")   //标题
                .description("演示项目")  //描述
                .version("1.0")   //版本
                .build();
    }
}

使用Swagger2进行接口测试
启动项目访问http://127.0.0.1:8080/swagger-ui.html，即可打开自动生成的可视化测试页面。使用Swagger2进行项目开发非常方便，不需要再借助apiPost或是postman等工具便可以进行接口测试，直接在swagger-ui.html页面便可以进行。

Swagger常用注解
Swagger提供了一系列注解来描述接口信息，包括接口说明、请求方法、请求参数、返回信息等。

使用示例：