springboot2.7配置swagger

### Spring Boot 2.7 中正确配置 Swagger 的最佳实践 在 Spring Boot 2.7 版本中，由于框架内部对路径匹配机制进行了调整，传统的基于 `WebMvcConfigurer` 和 `@EnableWebMvc` 的方式可能会引发一些兼容性问题。以下是针对该版本的最佳实践。 #### 1. 添加依赖项 为了集成 Swagger UI 和 OpenAPI 文档支持，需引入以下 Maven 或 Gradle 依赖： 对于 Maven 用户： ```xml <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> ``` 对于 Gradle 用户： ```groovy implementation 'io.springfox:springfox-boot-starter:3.0.0' ``` 需要注意的是，Springfox 是目前最常用的 Swagger 集成工具之一，但在高版本的 Spring Boot 下可能存在一定的适配挑战[^1]。 --- #### 2. 解决路径匹配器冲突 Spring Boot 2.6 及更高版本默认使用 `PathPatternParser` 替代了旧版中的 `AntPathMatcher`。这可能导致某些 Swagger 插件无法正常工作，具体表现为错误提示 `Failed to start bean ‘documentationPluginsBootstrapper’`[^2]。 解决方法如下： - **全局设置回退到 Ant 路径匹配器** 通过自定义 Bean 来强制恢复为 `AntPathMatcher`： ```java import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.PathMatchConfigurer; import org.springframework.web.util.UrlPathHelper; @Configuration public class WebConfig { public void configurePathMatch(PathMatchConfigurer configurer) { UrlPathHelper urlPathHelper = new UrlPathHelper(); urlPathHelper.setRemoveSemicolonContent(false); configurer.setUrlPathHelper(urlPathHelper); configurer.setUseRegisteredSuffixPatternMatchers(true); // 使用注册过的模式匹配器 } } ``` 此操作可以有效规避因路径解析策略变化带来的不兼容问题。 --- #### 3. 创建 Swagger 配置类 创建一个专门用于初始化 Swagger 功能的 Java 配置类： ```java import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; @Configuration public class SwaggerConfiguration { @Bean public Docket api() { return new Docket(DocumentationType.OAS_30) .select() .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 设置扫描包路径 .paths(PathSelectors.any()) .build() .apiInfo(apiInfo()); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Spring Boot REST API") // 自定义文档标题 .description("描述信息：这是一个示例项目接口文档") // 描述 .version("1.0.0") // 版本号 .license("Apache License Version 2.0") // 许可证 .build(); } } ``` 上述代码片段展示了如何构建并暴露 OAS (OpenAPI Specification) v3.0 格式的 API 文档。 --- #### 4. 启动类上的注意事项 如果需要扩展额外的功能（如跨域支持），可以在启动类上添加特定注解。然而，为了避免潜在冲突，建议仅保留必要注解而不随意加入其他修饰符。例如： ```java @SpringBootApplication @EnableSwagger2 // 如果使用 springdoc-openapi，则替换为此注解 public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } } ``` 注意：当启用 `@EnableWebMvc` 注解时，可能会影响自动配置行为，因此除非确实需要完全接管 MVC 层逻辑，否则应谨慎使用它。 --- #### 5. 测试访问地址 完成以上步骤后，可以通过浏览器打开以下 URL 查看生成好的交互式 API 文档界面： ``` http://localhost:8080/swagger-ui/index.html#/ ``` 或者直接下载 JSON/YAML 文件形式的元数据： ``` http://localhost:8080/v3/api-docs ``` --- ### 总结 综上所述，在 Spring Boot 2.7 上成功部署 Swagger 主要涉及以下几个方面的工作：合理选用第三方库版本、妥善处理新老路径匹配算法之间的差异以及科学编写相关配置文件等内容。