2025-06-11

喵星之旅-屯粮的松鼠-swagger和spring版本匹配

项目使用版本springboot2.3,springcloud2.2。

问题发现

1 2	@Value("${redis.client.password:hehe}") private String passwd;

如上代码，在配置中明确配置了redis.client.password的情况下，取值为“hehe”。即默认值优先级最高。整个取值顺序混乱。如果是一些开关配置，会导致代码执行分支也发生变化，系统功能异常。

事故原因

排查过程

1、通过debug确认确实是取值顺序问题。
2、去掉默认值，系统功能正常。
3、系统上一个版本确认无问题。
4、按照需求单独改造问题的项目，逐一确认哪个文件的改动造成的异常。最终改造完成之后功能正常。
5、将改造的代码和开发人员提交的进行对比，经确认，居然完全一样。
6、确认代码无误后，猜测来原因依赖jar。打包项目，然后解压，逐一和对jar依赖。
7、确认为swagger的版本号不一致，无其他异常。
8、将开发人员的代码进行版本替换，改为一致的swagger版本，后测试正常。
9、对所有项目进行逐一验证，确认异常项目的swagger版本和正常项目的版本情况。
10、确认结果为：异常项目swagger都是2.6版本，正常项目有2.8版本和2.10版本两种情况。有人的本地仓库中pom有问题，有2.6版本依赖。由于有大量私包，仓库需要人工导入一些内容，某些人没有及时更新版本。
11、所有异常的项目全都改为2.8版本，测试验证为功能已正常。

解决

根据系统的版本号，选择swagger2.8.0,问题消失。根据查到的资料，一般推荐2.9版本。

查到的一些参考资料

关于Swagger和Spring Boot的版本对应关系

关于Swagger和Spring Boot的版本对应关系，我们可以从以下几个方面进行详细解答：

1、 Swagger 2.x 与 Spring Boot 的版本对应

‌Spring Boot 1.5.x‌：通常与 ‌Swagger 2.7.0‌ 版本配合使用。这个组合在Spring Boot的早期版本中非常常见，适用于需要集成Swagger进行API文档生成的场景。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

‌Spring Boot 2.x‌：随着Spring Boot的更新，Swagger 2.x的版本也需要相应调整。例如，‌Spring Boot 2.5.3‌ 可以与 ‌Swagger 2.9.2‌ 配合使用。但在Spring Boot 2.6及以上版本，由于Spring MVC的路径匹配策略变更，直接使用Swagger 2.x可能会遇到兼容性问题。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2、解决Spring Boot 2.6及以上版本的兼容性问题

对于Spring Boot 2.6及以上版本，由于Spring MVC的路径匹配策略变更，直接使用Swagger 2.x可能会导致Failed to start bean ‘documentationPluginsBootstrapper’等错误。为了解决这个问题，可以采取以下措施：

‌修改路径匹配策略‌：在application.properties中添加以下配置，将路径匹配策略改回ANT_PATH_MATCHER。

1	spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

‌升级到Swagger 3.x‌：更彻底的解决方案是升级到Swagger 3.x（基于OpenAPI 3.0），它提供了更好的兼容性和更多的功能。例如，可以使用‌springdoc-openapi-starter-webmvc-ui‌来集成Swagger 3.x。

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>

3、Swagger 3.x 与 Spring Boot 的版本对应

‌Spring Boot 3.x‌：推荐使用‌springdoc-openapi-starter-webmvc-ui‌来集成Swagger 3.x。这个组合提供了良好的兼容性和丰富的功能，适用于需要生成和展示OpenAPI 3.0文档的场景。

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>

总结

在选择Swagger和Spring Boot的版本组合时，需要根据具体的Spring Boot版本来确定合适的Swagger版本。对于Spring Boot 2.6及以上版本，建议使用Swagger 3.x以获得更好的兼容性和功能。同时，注意在配置文件中进行必要的设置，以确保Swagger能够正常工作。

Spring Boot 2.3参数优先级失效

针对Swagger 2.6与Spring Boot 2.3参数优先级失效的问题，核心矛盾源于Springfox(Swagger2.x)的路径匹配策略与Spring Boot 2.3的默认配置冲突，同时涉及自定义参数解析器的优先级问题。以下是具体分析:

1.路径匹配策略冲突
Spring Boot 2.3默认使用 AntPathMatcher ,但Swagger 2.6在扫描API时可能因版本兼容性问题干扰参数解析流程，导致优先级混乱13
2.自定义解析器与 @RequestBody 的优先级冲突若项目中存在自定义参数解析器(如验签逻辑)，且接口参数使用了@RequestBody 注解Spring MVC会优先调用 RequestResponseBodyMethodProcessor，导致自定义解析器失效。

Swagger 2.6 与 Spring Boot 2.3 中 @Value 优先级失效问题解决方案

在使用 SpringFox Swagger 2.6.x 与 Spring Boot 2.3.x 时，可能会遇到 @Value 注解优先级失效的问题，特别是在配置 Swagger 相关参数时。
问题表现

通过 @Value 注入的配置值被默认值覆盖

环境变量和配置文件中的值无法正确覆盖 Swagger 配置

动态配置无法生效，始终使用代码中的硬编码值

主要原因

Spring Boot 2.3 对属性加载机制进行了调整，而 SpringFox Swagger 2.6.x 版本在初始化时可能过早创建 Bean，导致 @Value 注入时机不正确。

确保使用兼容的版本组合：

<properties>
    <spring-boot.version>2.3.12.RELEASE</spring-boot.version>
    <springfox.version>2.9.2</springfox.version>
</properties>