背景

当前项目是springboot2.5.9版本的springboot+mybatis-plus项目，需要升级到springboot3.5.0项目。

升级jdk版本为17以上

Spring Boot 3.x 需 ​Java 17+​，检查并升级 JDK：

<properties>
    <java.version>17</java.version>
</properties>

springboot版本修改

修改 pom.xml 中的父依赖版本：

<parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.5.9</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

升级版本

<parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.5.0</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

javax包更新

全局替换 javax.* 为 jakarta.*（涉及 Servlet、JPA 等）：

// 旧：import javax.servlet.HttpServletRequest;
// 新：import jakarta.servlet.HttpServletRequest;

mybatis-plus升级

 <dependency>
     <groupId>com.baomidou</groupId>
     <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
     <version>3.5.12</version>
 </dependency>
 
 <!--mybatis-plus分页插件使用必须依赖项-->
 <dependency>
     <groupId>com.baomidou</groupId>
     <artifactId>mybatis-plus-jsqlparser</artifactId>
     <version>3.5.12</version>
 </dependency>

这里面分页需要注意，必须引入新的依赖。

swagger升级springdoc

Spring 社区已明确推荐使用 ​springdoc-openapi​ 替代 springfox，因其原生支持 Jakarta EE 并与 Spring Boot 3.x 完全兼容

老版本的swagger

<dependency>
           <groupId>io.springfox</groupId>
           <artifactId>springfox-boot-starter</artifactId>
           <version>3.0.0</version>
 </dependency>

替换为新的swagger

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

springdoc配置

​

调整路径匹配策略

Spring Boot 3.x 默认使用 PathPatternParser，但 Swagger UI 需切换为传统 AntPathMatcher：
application.yml

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

删除swaggerconfig配置类

新增springdoc配置类

@Configuration
@SecurityScheme(
    name = "Bearer Authentication",
    type = SecuritySchemeType.HTTP,
    bearerFormat = "JWT",
    scheme = "bearer"
)
public class SpringDocConfig {
    
    @Bean
    public OpenAPI customOpenApi() {
        return new OpenAPI()
                .info(new Info()
                        .title("xxxAPI 文档")
                        .description("这是一个xxx系统的API文档。")
                        .version("1.0")
                        .contact(new Contact()
                                .name("开发团队")
                                .email("support@example.com")
                                .url("https://github.com/"))
                        .license(new License()
                                .name("MIT License")
                                .url("https://opensource.org/licenses/MIT"))
                        .termsOfService("http://example.com/terms/"))
                .externalDocs(new ExternalDocumentation()
                        .description("更多文档")
                        .url("http://example.com/docs"))
                .addSecurityItem(new SecurityRequirement().addList("Bearer Authentication"));
    }

    @Bean
    public GroupedOpenApi allApi() {
        return GroupedOpenApi.builder()
                .group("所有接口")
                .pathsToMatch("/**")
                .packagesToScan("com.xxx.xxx.controller")
                .build();
    }

spring-doc配置

springdoc:
  api-docs:
    enabled: true
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html
    url: /v3/api-docs
    disable-swagger-default-url: false
    tags-sorter: alpha
    operations-sorter: alpha
  packages-to-scan: com.xxx.controller
  paths-to-match: /**
  show-actuator: false
  default-produces-media-type: application/json
  default-consumes-media-type: application/json

其他修改：

依次将swagger的注解更改为springdoc的注解
主要使用springdoc的@Schema注解对类和属性进行标注：@Schema(description = "xxx对象")