springboot - 2.7.3版本 - （三）整合Swagger3

SpringBoot是Java开发中的一个流行框架，它简化了Spring应用的初始设置和配置，使得开发者可以更快地专注于业务逻辑。Swagger3则是用于构建RESTful API的API文档工具，它允许开发者通过注解来描述API，生成交互式的文档，极大地提高了前后端联调的效率。在SpringBoot项目中整合Swagger3，可以实现自动化接口文档的生成，为团队协作提供便利。 整合Swagger3需要引入相应的依赖。在SpringBoot的`pom.xml`文件中，添加`springdoc-openapi-ui`和`springdoc-openapi-data-rest`依赖。这两个依赖分别提供了UI界面和数据REST的支持。例如： ```xml <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.6.9</version> </dependency> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-data-rest</artifactId> <version>1.6.9</version> </dependency> ``` 接下来，我们需要在SpringBoot的主配置类上添加`@EnableOpenApi`注解，启动Swagger3的功能： ```java import org.springdoc.core.EnableSpringDocWebFlux; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; @SpringBootApplication @EnableSpringDocWebFlux public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } } ``` Swagger3的核心在于使用注解来描述API。例如，可以在Controller类和方法上使用`@Api`和`@ApiOperation`注解，分别表示API的分组和操作描述： ```java import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.tags.Tag; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; @RestController @Tag(name = "用户管理", description = "关于用户的相关操作") public class UserController { @GetMapping("/users") @Operation(summary = "获取所有用户信息", description = "返回所有的用户列表") public List<User> getAllUsers() { // 实现业务逻辑 } } ``` `@ApiParam`注解用于参数说明，可以应用于方法参数或路径参数，例如： ```java @GetMapping("/users/{id}") @Operation(summary = "获取单个用户信息", description = "根据用户ID获取用户详细信息") public User getUser(@ApiParam(value = "用户ID", example = "1", required = true) @PathVariable Long id) { // 实现业务逻辑 } ``` Swagger3还支持响应模型的定义，可以使用`@ApiModel`和`@ApiModelProperty`注解： ```java @ApiModel(description = "用户信息") public class User { @ApiModelProperty(value = "用户ID", example = "1", required = true) private Long id; @ApiModelProperty(value = "用户名", example = "testUser") private String name; // 其他属性和getter/setter方法 } ``` 整合完成后，访问`/swagger-ui/index.html`（根据项目配置可能会有所不同），就可以看到Swagger3生成的交互式文档。这个文档清晰地展示了所有API的信息，包括请求方法、URL、描述、参数以及示例，使得前端开发者可以直接通过这个文档进行接口测试和联调。 SpringBoot与Swagger3的整合能够帮助开发者高效地管理API文档，提高开发效率，降低沟通成本，是现代微服务架构中不可或缺的一部分。通过合理的注解配置，可以轻松实现API的清晰展示和便捷测试，是值得在实际项目中广泛采用的技术组合。