SpringBoot学习碎片之RESTful服务+Swagger

RESTful介绍

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

RESTful特点

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

RESTful API

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

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请求，用于部分更新资源

@RestController
public class UserController{
	@GetMapping("/user/{id}")
	public String getUserById(@PathVariable int id){
		return "根据ID获取用户";
	}
		@PostMapping("/user")
	public String save(User user){
		return "添加用户";
	}
		@PutMapping("/user")
	public String update(@PathVariable int id){
		return "更新用户";
	}
		@DeleteMapping("/user/{id}")
	public String deleteById(@PathVariable int id){
		return "根据ID删除用户";
	}
}

Swagger

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

使用Swagger生成Web API文档

• 在Spring Boot项目中集成Swagger同样非常简单，只需在项目中引入springfox-swagger2和springfox-swagger-ui依赖即可

配置Swagger

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;

/**
 * @author 20232194
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // com包下所有API都交给Swagger2处理
                .apis(RequestHandlerSelectors.basePackage("com"))
                .paths(PathSelectors.any()).build();
    }
    // API文档页面显示信息
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("项目演示API")
                .description("学习Swagger2的演示项目")
                .version("1.0")
                .build();
    }
}

注意事项

• Spring Boot 2.6.x之后与Swagger有版本冲突问题，需要在application.properties中加入以下配置

  spring.mvc.pathmatch.matching-strategy=ant_path_matcher