从 Mybatis-Plus 代码生成器（新）到 Swagger，到 springfox-swagger2，springfox-boot-starter，再到Knife4j

本地环境：

Java jdk1.8
Spring Boot 2.7.10
Mybatis-Plus 3.5.3.1

Mybatis-Plus 代码生成器（新） 是一个根据连接的数据库表结构快速生成 Mybatis-Plus 需要的 controller、entity、mapper、service 的工具。数据源 DATA_SOURCE_CONFIG 可以 H2 ，也可以是持久存储的 mysql 之类。

Mapper 代码生成器首先需要配置数据源，这边以 mysql 数据库为例（取自： baomidou/generator/samples/MySQLGeneratorTest.java ）：

    private static final DataSourceConfig DATA_SOURCE_CONFIG = new DataSourceConfig
        .Builder("jdbc:mysql://xxxx:3306/baomidou?serverTimezone=Asia/Shanghai", "root", "123456")
        .schema("baomidou")
        .build();

使用 FastAutoGenerator 可以直接使用 url、username、password 等参数来定义数据源，也可以使用上面定义的这种数据源。按照示例代码里注释的基本需要配置 4 项内容：

• globalConfig 全局配置
• packageConfig 包配置
• strategyConfig 策略配置
• templateEngine 模板引擎配置

需要注意两个路径修改，一个是全局配置里的 outputDir，这里定义输出文件的地址，要写项目核心代码目录 .../src/main/java，不配置的话，Mac 下测试是把文件输出到了 /tmp/ 文件夹下；另一个是包配置里的 xml 文件地址，默认是放在 mapper 类目录下的 xml 文件夹下，需要将其配置到 resources 目录下，如：.../src/main/resources/mapper。

模版引擎默认使用的是 velocity，这个也需要安装的：

<dependency>
    <groupId>org.apache.velocity</groupId>
    <artifactId>velocity-engine-core</artifactId>
    <version>2.3</version>
</dependency>

当然也可以安装其他的模板引擎，比如 Freemarker，或者 Beetl。

重复执行的时候会有一个提示：全局覆盖已有文件的配置已失效，已迁移到策略配置中。也就是示例代码全局配置中的 fileOverride()，需要放到策略配置里，针对 4 类文件分别设置：

...

.strategyConfig(builder -> {
    builder.addInclude("t_simple") // 设置需要生成的表名
        .addTablePrefix("t_", "c_"); // 设置过滤表前缀
        .controllerBuilder().enableRestStyle().enableHyphenStyle().enableFileOverride()
        .entityBuilder().enableLombok().enableFileOverride()
        .mapperBuilder().enableFileOverride()
        .serviceBuilder().enableFileOverride()
        .build();
})

多个表 addInclude 需要设置成 ArrayList，如果是全部表都要生成 mapper，则设置成空数组或者去掉这个方法。

到了这本来已经可以使用了，然后就发现 enableSwagger() 开启 swagger 模式，给 entity 实体及字段添加了 @ApiModel 和 @ApiModelProperty，而这些注解报错找不到。

百度这个注解提到了是一个 swagger 的注解，在 mvnrepository 中搜索 swagger，得到最匹配的项为

<!-- https://mvnrepository.com/artifact/io.swagger.core.v3/swagger-annotations -->
<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>2.2.8</version>
</dependency>

Swagger Annotations 显示 core v3，但版本还是 2.*。添加到 pom.xml 依赖中引入，@ApiModel 注解依然抱错。使用 swagger-models 也一样。

肯定是哪里出错了，然后查找 swagger 使用教程，在了解其主要作用是生成测试 API 的同时，也知道了需要引入的依赖应该是 springfox-swagger*：

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

在看到 mvnrepository 中最新版为 3.0.0 时，果断替换成新版本了。按照 SpringBoot中优雅的使用Swagger2-【1/2】 里添加了 SwaggerConfig 配置后，访问：http://localhost:8080/swagger-ui.html 报错：Failed to start bean 'documentationPluginsBootstrapper'。

按照 SpringBoot集成Swagger报错 里的说法，要么降低 SpringBoot 版本到 2.6.0 以下，要么修改 SpringBoot 路径匹配模式。

如果有对Spring Boot 2.6.0的文档进行研究，会发现2.6.0开始使用基于PathPatternParser的路径匹配，而Springfox版本一直没有更新还是使用的AntPathMatcher导致了这个问题，要处理问题也很简单，修改yaml文件，将SpringBoot路劲匹配模式修改为AntPathMatcher就可以了

修改 application.yml，添加：

spring:
  mvc:
    pathmatch:
      matching-strategy: ANT_PATH_MATCHER

重启后再次访问 /swagger-ui.html 返回的是 Whitelabel Error Page。百度 /swagger-ui.html 无法访问或者 swagger3 无法不到，也有两种方法，要么降低 swagger 版本到 2.*，要么使用 springfox-boot-starter 替换原来的依赖。

进一步了解知道，swagger2 的访问地址是 /swagger-ui.html 到了 swagger3 以后更新为 /swagger-ui/index.html。

依赖需要从 ：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>

改成：

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

springfox github 注意事项说明：

NOTE: Would love feedback to make this better

1. Remove explicit dependencies on springfox-swagger2
2. Remove any @EnableSwagger2... annotations
3. Add the springfox-boot-starter dependency
4. Springfox 3.x removes dependencies on guava and other 3rd party libraries (not zero dep yet! depends on spring plugin and open api libraries for annotations and models) so if you used guava predicates/functions those will need to transition to java 8 function interfaces.

springfox 官方文档 里也有相关的描述。

替换之后再次更新重启，访问 http://localhost:8080/swagger-ui/ (如果访问失败，则补全最后的 /index.html)，ok！

本来到这就好了，纯好奇之前的一个项目里面在整理依赖的时候没有发现 swagger，但我确实在控制器里看到过 @Api、@ApiOperation 等注解。全项目搜索 swagger 排查到 SecurityConfig 中有关联配置：

...

.antMatchers("/doc.html/**", "/swagger-resources/**", "/webjars/**", "/*/api-docs").permitAll()

根据 doc.html 访问路径确认找到了引入的包为 knife4j。浏览了两篇关于 knife4j 的使用教程：swagger文档增强工具knife4j使用详解，Swagger“升级版”——knife4j，大概理解了 knife4j 的定位。

knife4j 官网 有针对 Spring Boot 2 和 Spring Boot 3 分别做说明。

Spring Boot 3 只支持 OpenAPI3规范，knife4j 出了一个全新特供版本 knife4j-openapi3-jakarta-spring-boot-starter，底层框架完全使用 springdoc-openapi。

Spring Boot 2 则明显属于 OpenAPI2 和 OpenAPI3 都支持，OpenAPI2 版本 knife4j-openapi2-spring-boot-starter，底层框架完全使用的是 springfox。里面提到 不支持以Springfox框架为基础的OpenAPI3规范,放弃Springfox项目的后续版本适配支持工作，但 OpenAPI3 版本里面又说有两个 springfox 3.0.0 和 springdoc-openapi 两个版本，针对 Springfox3.0.0 版本会放弃。

这说法似乎有点矛盾，OpenAPI2 版本 knife4j-openapi2-spring-boot-starter 只支持 springfox 到 2.10.5，而 OpenAPI3 对应的knife4j-openapi3-spring-boot-starter 版本又两个底层框架都支持。从 mvnrepository 查看 knife4j-openapi3-spring-boot-starter 的依赖里并没有 springfox 3.0.0，而是 springdoc-openapi。

那么依赖 springfox 3.0.0 的 knife4j 版本又在哪里呢？查看百度教程里的依赖 knife4j-spring-boot-starter，发现其依赖中有一个 knife4j-spring-boot-autoconfigure，而这个库依赖中恰好有 springfox-boot-starter 3.0.0。不确定这是不是被 knife4j 遗弃的版本，但探索就到此为止了。

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

使用以上内容即可替换使用 knife4j 的 ui。此版本依赖 springfox-boot-starter 3.0.0，支持 OpenAPI2 和 OpenAPI3，或者可以使用 knife4j-openapi3-spring-boot-starter 版本仅支持 OpenAPI3。

访问地址：http://localhost:8080/doc.html