RESTful与Swagger

最新推荐文章于 2024-01-15 11:31:10 发布

翎刖

最新推荐文章于 2024-01-15 11:31:10 发布

阅读量316

点赞数 1

本文链接：https://blog.csdn.net/weixin_44434232/article/details/129685935

版权

RESTful与Swagger

RESTful
Swagger

RESTful

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

RESTful的特点

每一个URI代表一种资源
客户端使用GET、 POST、 PUT、 DELETE四种表示操作方式的动词对服务端资源进行操作：

GET用于获取资源
POST用于新建资源（也可以用于更新资源）
PUT用于更新资源
DELETE用于删除资源。

通过操作资源的表现形式来实现服务端请求操作。
资源的表现形式是JSON或者HTML。
客户端与服务端之间的交互在请求之间是无状态的，从客户端到服务端的每个请求都包含必需的信息。

Web API关键特性

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

HTTP状态码

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

SpringBoot实现RESTful API

SpringBoot提供的spring-boot-starter-web组件完全支持开发RESTful API，提供了与REST操作方式（GET、POST、PUT、DELETE）对应的注解。
@GetMapping：处理GET请求，获取资源。
@PostMapping：处理POST请求，新增资源。
@PutMapping：处理PUT请求，更新资源。
@DeleteMapping：处理DELETE请求，删除资源。
@PatchMapping：处理PATCH请求，用于部分更新资源。
在RESTful架构中，每个网址代表一种资源，所以URI中建议不要包含动词，只包含名词即可，而且所用的名词往往与数据库的表格名对应。
将@GetMapping("/delete?id=10")改为@DeleteMapping("/user/10")
用户管理模块API示例：
在这里插入图片描述

代码展示

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

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

{id}动态获取id值
@PathVariable注释获取前端传来的{id}值

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

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

Swagger

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

Swagger集成

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

<!--   Swagger依赖     -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

Swagger配置

SpringBoot 2.6.X后与Swagger有版本冲突问题，需要在application.properties中加入以下配置：

#Swagger配置
spring.mvc.pathmatch.matching-strategy=ant_path_matcher

@Configuration // 告诉Spring容器，这个类是一个配置类
@EnableSwagger2 // 启用Swagger2 功能
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()) // Docket
                .select() // ApiSelectorBuilder
                // com包下所有API都交给Swagger2管理
                .apis(RequestHandlerSelectors.basePackage("com"))
                .paths(PathSelectors.any()).build();
    }
    // API文档页面显示信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("折线图API") // 标题
                .description("学习Swagger2的折线图项目") // 描述
                .build();
    }
}