Spring Boot 3.x 引入springdoc-openapi (内置Swagger UI、webmvc-api)

Spring Boot 3.x 引入了对 Springdoc OpenAPI 的支持，这使得在应用中集成 Swagger UI、webmvc-api 变得更加简单和高效。Springdoc OpenAPI 是一个用于自动生成 OpenAPI 规范文档的库，它可以与 Spring Boot 应用无缝集成，并提供 Swagger UI 可视化接口，使得接口文档更加易于理解和使用。

一、什么是 Springdoc OpenAPI？

Springdoc OpenAPI 提供了一个强大的解决方案，可以根据 Java 代码中的注解自动生成 OpenAPI 3.0 规格的 API 文档。它能帮助开发者创建清晰的文档，并且与 Swagger UI 配合使用，使得 API 的使用更加自助化。

二、如何在 Spring Boot 3.x 中使用 Springdoc OpenAPI

在 Spring Boot 3.x 中集成 Springdoc OpenAPI 的步骤如下：

1. 添加依赖

首先，在 pom.xml 文件中添加 springdoc-openapi-ui 的相关依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.14</version> <!-- 请根据需要修改版本号 -->
</dependency>

2. 创建简单的 REST API

接下来，我们创建一个简单的 RESTful 控制器，利用注解来描述我们的 API 接口。

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @GetMapping("/hello")
    public String sayHello() {
        return "Hello, World!";
    }
}

3. 配置 Springdoc OpenAPI

在 Spring Boot 3.x 中，Springdoc OpenAPI 会在默认情况下启用，无需额外的配置。然而，你可以通过 application.properties 或 application.yml 文件来定制一些属性。例如：

springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.path=/swagger-ui.html

4. 访问 Swagger UI

当你运行 Spring Boot 应用后，访问 http://localhost:8080/swagger-ui.html，你就可以看到生成的 Swagger UI 界面。在这个界面中，你可以查看和测试所有的 API 接口。

三、添加 Swagger 注解

为了使文档更加完整，你可以使用更多的 Swagger 注解来描述你的 API，例如 @Operation 和 @ApiResponse 等。

以下是使用 Swagger 注解的示例：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @Operation(summary = "获取问候信息", 
               description = "返回问候的字符串", 
               responses = {
                   @ApiResponse(responseCode = "200", description = "成功返回问候信息"),
                   @ApiResponse(responseCode = "500", description = "内部服务器错误")
               })
    @GetMapping("/hello")
    public String sayHello() {
        return "Hello, World!";
    }
}

四、其他功能

除了基本的 API 文档生成，Springdoc OpenAPI 还支持多种特性，例如安全性配置、参数描述、分组文档、OpenAPI 拓展等等。你可以根据实际需求不断扩展 API 的描述。

总结

Springdoc OpenAPI 使得在 Spring Boot 3.x 应用中创建 API 文档变得非常简便。通过它的帮助，你可以快速生成 API 文档，并且通过 Swagger UI 提供了友好的用户界面。借助 Springdoc OpenAPI，你的项目可以达到更高的可维护性和更好的用户体验。