springboot3.0集成swagger

### Spring Boot 3.0 中集成 Swagger 实现 API 文档生成 #### Maven 依赖添加 为了使 Spring Boot 应用程序能够利用 Swagger 的功能来创建和展示 RESTful Web Services 的交互式文档，在项目的 `pom.xml` 文件中需加入如下依赖： ```xml <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> ``` 此操作引入了必要的库文件以便后续配置工作得以顺利开展[^2]。 #### 创建 Swagger 配置类 接着定义一个名为 `SwaggerConfig.java` 的 Java 类，该类负责初始化并定制化 Swagger UI 和 OpenAPI 规范的具体行为。下面是一个简单的例子说明如何设置基本信息如标题、描述以及版本号等属性： ```java import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; @Configuration public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.OAS_30) .select() .apis(RequestHandlerSelectors.basePackage("com.example")) .paths(PathSelectors.any()) .build(); } } ``` 上述代码片段展示了怎样通过编程方式指定哪些包下的接口会被纳入到最终产生的 API 文档之中。 #### Controller 层注解使用 为了让控制器方法被正确识别进而包含于自动生成的文档里，可以在相应的 RestController 上面加上特定的元数据标签。比如： ```java @Api(tags = "用户管理") @RestController @RequestMapping("/user") public class UserController { @ApiOperation("获取单个用户的详情") @GetMapping("/{id}") public JsonResult getUserById(@PathVariable("id") Long id) throws Exception{ // 方法体... } ... } ``` 这里运用了 `@Api` 来标记整个控制层组件所属的功能模块；而 `@ApiOperation` 则用来描述具体的操作含义及其参数细节[^4]。 #### 访问权限处理 (如果适用) 当应用程序实现了某种形式的身份验证机制之后，则可能需要特别注意确保 Swagger 资源路径不会受到不必要的保护措施影响。通常情况下可以通过调整安全策略的方式让这些特殊的 URI 可以免认证访问: ```java @Override protected void configure(HttpSecurity http) throws Exception { http.authorizeRequests().antMatchers( "/v3/api-docs/**", "/swagger-ui/**" ).permitAll(); } ``` 这段逻辑告诉框架对于匹配给定模式的所有请求都无需经过身份校验即可放行。 完成以上步骤后，一旦启动 Spring Boot 应用服务器，默认情况下就可以通过浏览器打开地址 `http://localhost:8080/swagger-ui/index.html?url=/v3/api-docs#/` 查看已构建好的在线版 API 接口指南页面了[^3]。