springboot 3.0引入swagger

### 在 Spring Boot 3.0 中集成 Swagger #### Maven 依赖配置 为了在 Spring Boot 3.0 中集成 Swagger，首先需要添加合适的 Maven 依赖。由于 Spring Boot 3.0 使用的是 Java 17 和 Jakarta EE (而非传统的 Javax)，因此需要使用兼容的库版本。推荐使用的依赖是 `springdoc-openapi` 而不是 `springfox`，因为后者尚未完全支持 Jakarta EE。 以下是所需的 Maven 依赖配置： ```xml <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-api</artifactId> <version>2.0.4</version> </dependency> ``` 此依赖会自动为项目提供 OpenAPI 文档生成功能以及 Swagger UI 的支持[^5]。 --- #### 配置类设置 如果需要自定义 Swagger 的行为，可以通过创建一个配置类来进行调整。例如，可以指定 API 的基本信息、分组策略等。以下是一个简单的配置示例： ```java import org.springdoc.core.models.GroupedOpenApi; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; @Configuration public class SwaggerConfig { @Bean public GroupedOpenApi publicApi() { return GroupedOpenApi.builder() .group("springboot-public") .pathsToMatch("/api/**") // 只匹配 /api/ 开头的路径 .build(); } } ``` 通过上述代码，您可以将不同的接口划分为多个分组以便于管理[^6]。 --- #### Controller 注解 为了让 Swagger 正确识别并展示您的接口文档，在控制器方法中应适当添加注解。常用的注解包括但不限于以下几个： - `@Operation`: 描述操作的具体功能。 - `@Parameter`: 定义请求参数的相关信息。 - `@ApiResponse`: 响应状态码及其含义说明。 下面是一段带有这些注解的例子： ```java @RestController @RequestMapping("/example") public class ExampleController { @Operation(summary = "获取用户详情", description = "根据ID查询单个用户的详细资料") @ApiResponse(responseCode = "200", description = "成功返回用户对象") @GetMapping("/{id}") public ResponseEntity<UserDto> getUserById(@Parameter(description = "目标用户的唯一标识符") @PathVariable Long id) { UserDto user = userService.findById(id); return new ResponseEntity<>(user, HttpStatus.OK); } } ``` 以上代码片段展示了如何利用 Swagger 提供的功能来增强 RESTful 接口的可读性和可用性[^7]。 --- #### 访问地址 完成上述步骤之后，当您运行 Spring Boot 应用程序时，默认情况下可以在浏览器里打开以下链接查看生成好的交互式 API 文档界面： - **Swagger UI**: `http://localhost:8080/swagger-ui.html` - 或者新版本可能位于：`http://localhost:8080/v3/api-docs/ui` 请注意实际端口号取决于应用本身的配置情况[^8]。 --- #### 权限控制（如有必要） 如果您已经在安全模块中设置了全局认证机制，则还需要特别处理 Swagger 所需资源的免登录访问权限。通常是在 WebSecurityConfigurerAdapter 子类或者 SecurityFilterChain Bean 方法内部加入类似这样的规则： ```java @Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http.authorizeHttpRequests((authz) -> authz .requestMatchers("/v3/api-docs/**", "/swagger-ui/**").permitAll() // 放行 swagger 相关 URI .anyRequest().authenticated()); return http.build(); } ``` 这样做的目的是让未授权用户也能正常浏览 API 文档页面而不会被拦截重定向到登录页去[^9]。 ---