构建RESTful服务——使用Swagger生成Web API文档

构建RESTful服务

1. RESTful介绍

1.1 简介

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

1.2 特点：

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

1.3 RESTful API

符合RESTful规范的Web API需要具备如下两个关键特性:

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

1.4 HTTP状态码

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

1.5 Spring Boot 实现 RESTful API

Spring Boot提供的 spring-boot-starter-web 组件完全支持开发 RESTful API ，提供了与REST操作方式(GET、POST、PUT、DELETE)对应的注解。

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

请求路径的不同
在RESTful架构中，每个网址代表一种资源，所以URI中建议不要包含动词，只包含名词即可，而且所用的名词往往与数据库的表格名对应。

根据id查询用户信息
规范演示对✔

localhost:8080/user/1

不规范错 X

localhost:8080/query/user?id=1

2. 构建RESTful应用接口

@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删除用户";
    }
}

3. 使用Swagger生成Web API文档

3.1 Swagger简介

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

3.2 引入相关依赖

在Spring Boot项目中集成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>

3.3 核心配置文件application.properties

使用springboot2.6.0后，配置swagger，不论是2.9.2还是3.0.0都报错
解决方法：配置文件中加入 application.properties

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

3.4 创建配置类

package com.guo.springboot.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration //声明为配置类
@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();
    }
}

3.5 使用Swagger2进行接口测试

访问：http://localhost:8080/swagger-ui.html
即可打开自动生成可视化测试页面