springdoc spring boot3

科普文章：使用springdoc生成OpenAPI文档

简介

在现代的Web开发中，使用OpenAPI文档来描述和展示API接口已经成为一种标准做法。OpenAPI文档可以帮助开发者理解和使用API，同时也可以作为API的合同，让不同的团队之间能够更好地协作。在Spring Boot应用中，我们可以使用springdoc来方便地生成OpenAPI文档。

什么是springdoc

springdoc是一个用于生成OpenAPI文档的开源项目，它基于Spring Boot和Spring WebFlux。使用springdoc，我们可以通过简单的注解来描述API接口，并且springdoc会自动将这些注解转换为OpenAPI规范的文档。

安装和配置

要使用springdoc生成OpenAPI文档，我们首先需要在Spring Boot项目中添加相关的依赖。在pom.xml文件中，我们添加以下依赖：

<dependencies>
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-ui</artifactId>
        <version>1.5.12</version>
    </dependency>
</dependencies>

完成依赖的添加后，我们需要配置springdoc来启用OpenAPI文档的生成。在Spring Boot的配置类或配置文件中，添加以下配置：

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info().title(My API).version(1.0.0));
    }
}

上述配置中，我们创建了一个OpenAPI的实例，并设置了API的标题和版本。你可以根据自己的需要进行修改。

使用示例

假设我们有一个简单的RESTful API，提供了创建和获取用户的功能。我们可以使用springdoc注解来描述这些API接口，并生成OpenAPI文档。

首先，我们在控制器类上添加@Tag注解，用于给这个接口组命名：

@RestController
@RequestMapping(/users)
@Tag(name = 用户管理)
public class UserController {

    @PostMapping
    @Operation(summary = 创建用户)
    public ResponseEntity<User> createUser(@RequestBody User user) {
        // 创建用户的逻辑
    }

    @GetMapping(/{id})
    @Operation(summary = 获取用户)
    public ResponseEntity<User> getUser(@PathVariable Long id) {
        // 获取用户的逻辑
    }
}

在上述代码中，我们使用@Tag注解给这个接口组命名为"用户管理"，并使用@Operation注解来描述每个具体的API接口的功能。

接下来，我们启动Spring Boot应用，并访问以下地址：http://localhost:8080/swagger-ui.html。在这个页面上，我们可以看到生成的OpenAPI文档，并且可以在页面上进行测试和调试。

总结

使用springdoc，我们可以方便地生成OpenAPI文档，并且通过访问swagger-ui页面来浏览和测试API接口。通过使用注解来描述API接口，我们可以清晰地了解每个接口的功能，同时也方便了接口的使用和维护。希望本文对你理解和使用springdoc有所帮助。

参考链接

• [springdoc官方文档](
• [springdoc GitHub仓库](