哎呀，说实话，SpringBoot 2.x 升级到 3.x 那事儿啊，真是让人又爱又恨。

先说结论吧：Swagger 那玩意儿直接搬不动了得换成 SpringDoc OpenAPI。

别慌，我这就把迁移过程拆成几块儿聊聊。

SpringBoot 3.x 要求 Java 17 或geng高。

Ru果你还在用 JDK8，那升级前先把编译器、IDE dou调好。

哈哈，我之前还有同事因为 JDK 不兼容报错，一头雾水。

别急，改完以后再跑单元测试，确保老功Neng还Neng跑通。

Zui关键的一步，就是把原来的 springfox-swagger2springfox-swagger-ui 删掉。

然后加上 SpringDoc 的 starter：

    org.springdoc
    springdoc-openapi-starter-webmvc-api
    2.5.0

别忘了把父 POM 的 改成Zui新的 3.x 系列。

比如 MyBatis‑Plus，要换成 mybatis-plus-spring-boot3-starter。

还有Ru果用了 validation，要从 javax.validation 改成 jakarta.validation。

这里面Zui坑的是注解名变了好在官方给了对照表。

举个例子：

import io.swagger.annotations.*;
@Api
public class UserController {
    @ApiOperation
    public User getUser String userId) {
        // ...
    }
}
@ApiModel
class User {
    @ApiModelProperty
    private String userId;
    @ApiModelProperty
    private String username;
}

import io.swagger.v3.oas.annotations.*;
import io.swagger.v3.oas.annotations.tags.Tag;
import io.swagger.v3.oas.annotations.media.Schema;
@Tag
public class UserController {
    @Operation
    public User getUser String userId) {
        // ...
    }
}
@Schema
class User {
    @Schema
    private String userId;
    @Schema
    private String username;
}

Swa​​gger 原来的配置大多是用 Docket 配合 @EnableSwagger2.

Spa​​rDoc 则geng轻量，只需要声明一个 GroupedOpenApi Bean。

@Configuration
public class SpringDocConfig {
    @Bean
    public GroupedOpenApi publicApi {
        return GroupedOpenApi.builder
                .group
                .packagesToScan
                .build;
    }
}

P.S. 有时候 IDE 自动补全会把 .properties -file 写成 .properties., 导致加载失败。哈哈，这种细节真的Neng把人逼疯。

A：百度爬虫默认会过滤掉hen多 JS 渲染的页面而 Swagger UI 是前端用 JS 动态生成文档的。要想被收录，需要给出静态化的 HTML（比如使用 springdoc-openapi-webmvc-ui 并开启 /v3/api-docs/swagger-config.json?) 或者在 robots.txt 中明确放行 /swagger-ui.html 路径。另外把页面标题和 meta 描述写得geng友好点，也Neng提升收录概率。说实话，这事儿跟 SEO geng挂钩，不是代码本身的问题啦。

Maven 中Ru果还有旧版 spring-boot-starter-test 的依赖，需要升级到对应的 3.x，否则测试报错；

Kotlin 项目同样要把所有 javax.* 包改成 jakarta.*；

If you use Actuator, add /actuator/openapi/** 才Neng让它一起暴露出来；

Caching 注解也迁移到了 jakarta.cache 包下不改会报 NoClassDefFoundError；

MVC 配置里Ru果用了旧的 WebMvcConfigurerAdapter，要改成实现 WebMvcConfigurer 接口；

"哈哈"…别笑，我当时真的是手抖删掉了一个重要 bean，项目直接启动不了…害！赶紧回滚再来一次。

- 把 pom.xml 的 parent 换成Zui新的 spring‑boot‑starter‑parent 版本。

   org.springframework.boot
   spring-boot-starter-parent
   3.1.4
   

- 全局搜索 “springfox” 删除相关依赖。

- 加入 SpringDoc OpenAPI starter。

- 用 IDE 把所有 `javax.` 替换为 `jakarta.` 。

- 把老旧的 Swagger 注解批量替换为对应的新注解。Ke以写个小脚本，用正则搞定：

grep -rl 'io.swagger.annotations' src/main/java | xargs sed -i 's/io.swagger.annotations/io.swagger.v3.oas.annotations/g'
grep -rl '@Api' src/main/java | xargs sed -i 's/@Api/@Tag/g'
# ... 按需继续

- 在配置类里加上 SpringDocConfig，上面Yi经示例完毕。

- 启动项目，用浏览器打开 /swagger-ui.html查kan文档是否渲染正常。