RESTful API规范、Swagger

RESTful API

介绍

• RESTful是目前流行的互联网软件服务架构设计风格。

• REST（Representational State Transfer，表述性状态转移）定义了互联网软件服务的 架构原则，如果一个架构符合REST原则，则称之为RESTful架构。

• REST并不是一个标准，它更像一组客户端和服务端交互时的架构理念和设计原 则，基于这种架构理念和设计原则的Web API更加简洁，更有层次。

RESTful API 特点

• 每一个URI代表一种资源。

• 客户端使用GET、POST、PUT、DELETE四种表示操作方式的动词对服务端资源进行操作：GET用于获取资源，POST用于新建资源（也可以用于更新资源），PUT用于更新资源，DELETE用于删除资源。

• 通过操作资源的表现形式来实现服务端请求操作。

• 资源的表现形式是JSON或者HTML。

• 客户端与服务端之间的交互在请求之间是无状态的,从客户端到服务端的每个请求都包含必需的信息。

HTTP Method

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

以删除用户为例：

• 传统情况：

  前端发出get请求

  1	http://localhost/del?user=10

  后端查找并删除id为10的用户。

• RESTful规范

  前端发出delete请求

  1	http://localhost/user/10

  注意：RESTful规范中的URL路径避免使用动词。

示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

@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(User user){
        return "更新用户";
    }

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

}

这里的{id}表示从路径中动态获取，方法声明中加上@PathVariable注解表示该变量从URL中获取。

Swagger

• Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务，是非常流行的API表达工具。

• Swagger能够自动生成完善的RESTful API文档,,同时并根据后台代码的修改同步更新,同时提供完整的测试页面来调试API。

如下图所示，可以参考DOMjudge的开发页面。

在项目中使用

以下内容部分不适合最新的SpringBoot，请先完整查看。

添加如下依赖（gradle）：

1
2

implementation 'io.springfox:springfox-swagger2:3.0.0'
implementation 'io.springfox:springfox-swagger-ui:3.0.0'

需要一个配置类，参考实现如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

@Configuration // 告诉Spring容器，这个类是一个配置类
@EnableSwagger2 // 启用Swagger功能
public class Swagger2Config 
{
    //配置Swagger2相关的bean
    @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的演示项目") // 描述
                .build();
    }
}

访问下面地址查看：

1

http://localhost:8080/swagger-ui.html

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

1	spring.mvc.pathmatch.matching-strategy=ant_path_matcher

如果你仍然报错，请复原上述操作，按下面的说明操作：

高版本 Spring Boot 已经全面迁移到 Jakarta EE（包名jakarta.servlet），而老旧的 Swagger 3.0.0 还依赖旧的 Java EE（包名javax.servlet）。

解决方案：改用适配高版本的 SpringDoc

1	implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:3.0.1'

可能不需要之前写的Swagger2Config类，因为SpringDoc几乎零配置就能用。

如果需要自定义，新的配置类参考实现如下：

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

@Configuration public class SpringDocConfig { // 对应原来的 apiInfo() @Bean public OpenAPI customOpenAPI() { return new OpenAPI() .info(new Info() .title("演示项目API") .description("学习SpringDoc的演示项目") .version("1.0.0")); } // 对应原来的 .apis(RequestHandlerSelectors.basePackage("com")) @Bean public GroupedOpenApi publicApi() { return GroupedOpenApi.builder() .group("com-api") .pathsToMatch("/**") // 对应原来的 PathSelectors.any() .packagesToScan("com") // 对应原来的 basePackage("com") .build(); } }

新的页面通过如下地址访问

• Swagger UI 页面：http://localhost:8080/swagger-ui/index.html
• OpenAPI 规范接口：http://localhost:8080/v3/api-docs（返回 JSON 格式的 API 文档）

新旧注解对照表