【SpringDoc】项目中使用SpringDoc管理与测试接口

一、介绍SpringDoc

SpringDoc是一个用于生成和展示API文档的开源库，它基于Spring Boot和OpenAPI规范。它提供了一种简单而强大的方式来自动生成API文档，并且与Spring框架无缝集成。

SpringDoc的主要特点包括：

1. 自动生成API文档：SpringDoc可以根据Spring Boot程序中的代码、注解和配置自动生成API文档。它会解析控制器、路径映射、请求和响应对象，并将它们转换为清晰的API文档。我们只需要添加一些注解和配置，SpringDoc就能够自动扫描和解析代码，并生成相应的API文档。

2. 支持OpenAPI规范：SpringDoc遵循OpenAPI规范（以前称为Swagger规范），这是一个用于描述和定义RESTful API的行业标准。通过使用SpringDoc，我们可以轻松地创建符合OpenAPI规范的API文档。它支持OpenAPI 3.x版本，并提供了一系列的注解和配置选项，使能够定义API的路径、参数、请求和响应等信息。

3. 集成简单：SpringDoc与Spring Boot框架无缝集成，只需添加几个依赖和配置即可开始使用。它使用Spring Boot的自动配置功能，可以自动扫描和配置应用程序，无需额外的繁琐配置。您可以通过Maven或Gradle添加SpringDoc的依赖，并在应用程序的配置类中添加相应的注解，即可启用SpringDoc的功能。

4. 丰富的功能和定制选项：SpringDoc提供了许多功能和选项，使我们能够根据自己的需求进行定制。我们可以使用注解和配置选项来定义API的安全要求、安全方案、响应模型、错误处理等。它还支持文档的分组、版本控制、主题样式定制等功能，使您能够创建出符合需求的精美API文档。

5. 交互式文档界面：SpringDoc生成的API文档具有交互式的界面，可以在浏览器中直接查看和测试API。它提供了一个用户友好的UI界面，展示了API的路径、参数、请求和响应等信息，并提供了测试功能，可以直接在文档界面上发送请求并查看响应结果。

总而言之，SpringDoc是一个强大而易用的API文档生成工具，它能够帮助开发人员快速生成符合OpenAPI规范的API文档，并提供了丰富的功能和定制选项。通过使用SpringDoc，我们可以更好地管理和展示您的API，可以在文档界面上直接测试API，并查看请求和响应的结果。

二、项目中集成SpringDoc

在Spring Boot项目中使用SpringDoc来生成和展示API文档非常简单。下面是一个简单的教程，帮助我们在项目中使用SpringDoc。

步骤 1：添加依赖

首先，需要在项目的构建文件pom.xml中添加SpringDoc的依赖。

<dependency>
	<groupId>org.springdoc</groupId>
	<artifactId>springdoc-openapi-spring-boot-2-webmvc</artifactId>
	<version>3.1.5</version>
</dependency>

步骤 2：配置SpringDoc
在application.yml文件中定义SpringDoc的配置信息

springdoc:
  api-docs:
    enabled: true
    path: /doc-api.html
  swagger-ui:
    path: /swagger-ui.html
    disable-swagger-default-url: on

步骤 3：启用SpringDoc

SpringDoc的配置需要我们创建一个配置类，至于类的名字叫什么无所谓。例如我在包里面创建SpringDocConfig类。

@Configuration
@OpenAPIDefinition(
        info = @Info(
        	title = "My API",
        	description = "This is a sample API",
        	version = "1.0"
  	    )
)
public class SpringDocConfig {

}

步骤 4：添加注释

在Spring Boot应用程序中的控制器类和方法上添加适当的注解来定义API的路径、请求方法、参数、请求体、响应等信息。以下是一些常用的注解：

• @RestController：将类标记为控制器类。
• @GetMapping、@PostMapping、@PutMapping、@DeleteMapping：定义不同的HTTP请求方法。
• @Operation：定义操作的描述。
• @Parameter：定义参数的描述。
• @RequestBody：定义请求体的描述。
• @ApiResponse：定义响应的描述。

通过使用这些注解，可以清晰地定义API，并为每个操作和参数提供详细的描述。如下：

@RestController // 声明该类为一个RESTful控制器
@RequestMapping("/user") // 定义该控制器的根路径为/user
@Tag(description = "用户Web接口") // 为该控制器添加一个描述标签
public class UserController {

    @PostMapping("/checkCode") // 处理HTTP POST请求的路径为/user/checkCode
    @Operation(summary = "检测登录验证码") // 为该方法添加一个简要描述
    public ResponseEntity<R> checkCode(@Valid @RequestBody CheckCodeForm form) {
        // 处理检测登录验证码的逻辑
        return ResponseEntity.ok().body(R.ok().put("result", true));
    }
}

步骤 5：访问API文档

启动Spring Boot应用程序，并在浏览器中访问生成的API文档。默认情况下，API文档的URL是/swagger-ui.html。

例如，如果应用程序运行在本地的端口8080上，您可以在浏览器中访问http://localhost:8080/项目名称/swagger-ui.html来查看API文档。

SpringDoc提供了一个交互式的UI界面，用于展示生成的API文档。我们可以在文档界面上查看和测试API的各个方面，包括路径、参数、请求和响应等信息。