springdoc-openapi 替换 Swagger2 总结
为什么要替换为 springdoc-openapi
-
Springfox/Swagger2 已停止维护
无法适配 Spring Boot 新版本，存在安全和兼容性隐患。 -
与 Spring Boot 2.6+ 兼容性差
经常出现启动报错、NPE 等严重兼容性问题，社区已无有效修复方案。 -
springdoc-openapi 支持 OpenAPI 3 标准
完全支持 OpenAPI 3 规范，功能更强大，文档结构更清晰，支持更多新特性。
迁移主要更改
-
Maven 依赖调整
- 移除（或注释）Springfox/Swagger2 相关依赖（如
io.springfox:springfox-boot-starter:3.0.0）。 - 新增 springdoc-openapi 依赖。
- 移除（或注释）Springfox/Swagger2 相关依赖（如
-
注解替换
- 将 Controller 和实体类中的 Swagger2 注解替换为 OpenAPI 3 注解：
@Api→@Tag@ApiOperation→@Operation@ApiModelProperty→@Schema
- 将 Controller 和实体类中的 Swagger2 注解替换为 OpenAPI 3 注解：
-
配置类调整
- 删除原有的
Swagger2Config.java配置类（如有）。 - 新增
OpenApiConfig.java，用于自定义文档信息（如标题、描述等）。
- 删除原有的
项目搭建
1. 生成 Spring Boot 聚合项目
在 pom.xml 中添加相关依赖：
- 父工程 `pom` 设置 `<parent>` 继承 Spring Boot 版本控制，设置 `<modules>` 管理子模块。
2. 子模块初始化
目录结构
添加依赖
修改 Spring Boot 配置文件 application.yml：
- 添加数据源配置和 MyBatis 的 `mapper.yml` 路径配置。- 
MyBatis Generator 配置：
- `generatorConfig.xml`：配置连接数据库信息，生成的 Java 实体类、Mapper.xml 文件、Mapper 接口文件所在包及位置等。- `MyBatisConfig.java`：用于配置需要动态生成的 mapper 接口路径，让 Spring 能识别和管理 Mapper 接口。- `CommentGenerator.java`：自定义注释生成器，继承自 MBG 的 DefaultCommentGenerator，用于在生成的实体类字段上添加数据库备注等注释，提升代码可读性。- `Generator.java`：generator 的 main 函数生成代码，读取 `generatorConfig.xml`，解析并执行代码。- `generator.properties`：结合 generatorConfig.xml 使用，作为参数引用，通过 ${} 占位符引用- `PmsBrandMapper.xml`：SQL 映射文件，定义了具体的 SQL 语句和结果映射关系，供 Mapper 接口调用。- `PmsBrandMapper.java`：Mapper 接口，定义了对 PmsBrand 表的增删改查（CRUD）方法，供 Service 层调用，实际 SQL 由 MyBatis 实现。- `PmsBrand.java`：实体类，对应数据库中的 PmsBrand 表，每个字段映射一列，用于数据传递。- `PmsBrandExample.java`：条件构造器类，用于动态生成复杂的查询条件（如 where、order by），常配合 Mapper 的 selectByExample 等方法实现灵活查询。
Controller 接口实现：
- 实现 `PmsBrand` 表的添加、修改、删除及分页查询接口。- `IErrorCode.java`：封装 API 的错误码- `ResultCode.java`：实现 IErrorCode 接口，枚举常用 API 操作码- `CommonResult.java`：结合 ResultCode，实现通用返回对象- `CommonPage.java`：分页数据封装类- `PmsBrandService.java`：接口文件- `PmsBrandServiceImpl.java`：实现接口- `PmsBrandController.java`：实现具体功能
3. 加入Springfox/Swagger2 UI（高版本废弃，可采用springdoc-openapi
目录结构
- 若需要调整为springdoc-openapi，可前往问题解答查看- 
依赖引入：
- springfox swagger官方Starter：io.springfox:springfox-boot-starter:3.0.0
application.yml：新增Spring MVC路径匹配策略
- spring.mvc.pathmatch.matching-strategy = ANT_PATH_MATCHER- ANT_PATH_MATCHER 表示使用传统的 Ant 风格路径匹配（如 /api/**），而不是 Spring 5.3+ 默认的 PathPatternParser。常用于解决升级 Spring Boot 后，部分路由、拦截器、Swagger 等路径匹配不兼容的问题。
Swagger2配置
- `Swagger2Config.java`：Swagger 的核心配置类，创建并配置 Docket，指定扫描的 Controller 包，设置 API 信息。- `PmsBrandController.java`：调整内容，补充Swagger 注解- `CommentGenerator.java`：调整注释生成器，配置后，用于在自动生成的实体类字段上添加 @ApiModelProperty 注解- 运行Generator.java重新生成文件- 运行项目，即可访问http://localhost:8080/swagger-ui/
4. 整合Redis实现缓存功能
目录结构
- 
依赖引入：
- Spring Data Redis依赖配置：org.springframework.boot:spring-boot-maven-plugin
application.yml：
- 添加Redis的配置及Redis中自定义key的配置。
RedisConfig.java：
- 用于自定义和优化 Spring Boot 项目中 Redis 的序列化方式、缓存管理等，保证数据能正确存储和读取，提升兼容性和性能。
RedisService.java：
- redis接口用于定义一些常用Redis操作- `RedisServiceImpl.java`：注入StringRedisTemplate，实现RedisService接口
UmsMemberService.java：
- 定义会员相关的业务接口（如生成、校验验证码）。- `UmsMemberServiceImpl.java`：实现会员业务逻辑，调用 RedisService 进行验证码的存取。- 生成验证码时，将自定义的Redis键值加上手机号生成一个Redis的key,以验证码为value存入到Redis中，并设置过期时间为自己配置的时间（这里为120s）。校验验证码时根据手机号码来获取Redis里面存储的验证码，并与传入的验证码进行比对。- `UmsMemberController.java`：编写 Controller 层，暴露获取和校验验证码的接口，调用 UmsMemberService。
5. 整合SpringSecurity和JWT实现认证和授权
目录结构
依赖引入：
- SpringSecurity依赖配置：org.springframework.boot:spring-boot-starter-security- JWT(Json Web Token)登录支持：io.jsonwebtoken:jjwt:0.9.1- Hutool Java工具包：cn.hutool:hutool-all:5.8.9
application.yml：
- 添加jwt，secure相关配置
AdminUserDetails.java：
- 先定义用户信息封装类，便于后续认证和授权。
UmsResource.java：
- 表示系统中的“后台资源”实体，是数据库表的映射
UmsAdminService.java：
- 定义用户管理接口，明确需要哪些功能。
UmsAdminServiceImpl.java：
- 实现接口，完成用户、资源、登录等核心业务逻辑。
JwtTokenUtil.java：
- 实现 JWT 生成和校验工具类，供登录和认证使用。
MallSecurityConfig.java：
- 配置如何获取用户信息，注入自定义的 UserDetailsService。
JwtAuthenticationTokenFilter.java：
- 实现 JWT 认证过滤器，集成到 Spring Security。
IgnoreUrlsConfig.java：
- 配置白名单路径，便于安全配置。
RestAuthenticationEntryPoint.java 和 RestfulAccessDeniedHandler：
- 实现自定义异常处理，提升接口友好性。
SecurityConfig.java：
- 配置安全规则、过滤器链、异常处理等，集成前面所有组件。
UmsAdminController.java：
- 实现接口层，调用 Service 提供登录和资源查询等功能。
6. 整合Elasticsearch实现商品搜索
目录结构
依赖引入：
- Elasticsearch相关依赖：org.springframework.boot:spring-boot-starter-data-elasticsearch
安装Elasticsearch，Kibana
- 注意Spring Boot与Elasticsearch版本兼容性，- Elasticsearch- 7.17.29- 下载zip包，并解压到指定目录，下载地址：https://www.elastic.co/downloads/past-releases/elasticsearch-7-17-29- 安装中文分词插件：elasticsearch-plugin install https://get.infini.cloud/elasticsearch/analysis-ik/7.17.29- 执行elasticsearch.bat- Kibana- 7.17.29- 下载zip包，并解压到指定目录，下载地址：https://www.elastic.co/downloads/past-releases/kibana-7-17-29- 执行kibana.bat- 访问http://localhost:5601 即可打开Kibana的用户界面
application.yml：
- 添加Elasticsearch相关配置
EsProductAttributeValue.java和EsProduct.java：
- 定义ES文档结构- 定义了存储在Elasticsearch中的商品和商品属性的数据结构（文档结构），通过注解指定了索引、字段类型、分词器等。关系：决定了Elasticsearch索引的数据模型，部署Elasticsearch后，这些类对应ES中的文档结构。- 不需要中文分词的字段设置成@Field(type = FieldType.Keyword)类型，需要中文分词的设置成@Field(analyzer = "ik_max_word",type = FieldType.Text)类型。
EsProductDao.java：
- 自定义DAO接口，用于从数据库中查询商品数据，为后续导入Elasticsearch做准备。
EsProductRepository.java：
- 添加接口用于操作Elasticsearch- 继承ElasticsearchRepository接口，这样就拥有了一些基本的Elasticsearch数据操作方法，同时定义了一个衍生查询方法。
EsProductService.java：
- 添加接口- `EsProductServiceImpl.java`：EsProductService接口的实现类
EsProductController.java：
- 暴露REST API接口，供前端或其他服务调用，实现商品的ES相关操作。关系：最终通过Service间接操作Elasticsearch。
7. 整合Mongodb实现文档操作
目录结构
依赖引入：
- MongoDB相关依赖：org.springframework.boot:spring-boot-starter-data-mongodb
安装Mongodb与Studio 3T
- 注意Spring Boot与Mongodb版本兼容性，- Mongodb- 4.4.29- 下载zip包，并解压到指定目录，下载地址：https://www.mongodb.com/try/download/community-edition/releases/archive- 新建配置文件mongod.cfg(mongodb.conf)，新建data目录用于存放数据，- 启动服务，执行：mongod --config "配置文件"- 启动shell，执行：mongo- 注册成Windows服务：mongod --config "配置文件" --install --serviceName "MongoDB" - 移除服务：mongod.exe --remove --config "配置文件" --serviceName "MongoDB"- Studio 3T(Robo 3T)- 下载zip包，并解压到指定目录，执行安装程序，下载地址：https://robomongo.org/
application.yml：
- 添加Mongodb相关配置
MemberReadHistory.java：
- 定义 MongoDB 文档结构- 文档对象的ID域添加@Id注解，需要检索的字段添加@Indexed注解。
MemberReadHistoryRepository.java：
- 用于与 MongoDB 交互- 继承MongoRepository接口，这样就拥有了一些基本的Mongodb数据操作方法，同时定义了一个衍生查询方法。
MemberReadHistoryService.java：
- 声明业务方法，定义了浏览历史的服务接口，声明了创建、删除、查询浏览历史的方法，便于后续实现具体业务逻辑。
MemberReadHistoryServiceImpl.java：
- 实现了服务接口，具体通过注入的 MemberReadHistoryRepository（MongoDB JPA 仓库）来操作 MongoDB，实现浏览历史的增删查。
MemberReadHistoryController.java：
- 暴露 REST API，调用 Service。，供前端或其他服务调用，实现浏览历史的创建、删除、查询功能。
8. 整合RabbitMQ实现延迟消息
目录结构
依赖引入：
- Spring AMQP相关依赖：org.springframework.boot:spring-boot-starter-amqp
安装Erlang与RabbitMQ
- Erlang- 下载zip包，并解压到指定目录，配置环境变量，下载地址：https://www.erlang.org/patches/otp-27.3.4.3- RabbitMQ- 下载zip包，并解压到指定目录，下载地址：https://github.com/rabbitmq/rabbitmq-server/releases/tag/v4.1.4- 启动web管理界面：rabbitmq-plugins enable rabbitmq_management- 执行，在后台执行需加 -detached：rabbitmq-server.bat- 访问：http://localhost:15672/- 默认账号：guest/guest- 创建帐号并设置其角色为管理员：mall mall
application.yml：
- 修改配置，在spring节点下添加RabbitMQ相关配置。
QueueEnum.java：
- 消息队列和交换机的枚举配置，统一管理队列、交换机、路由键的名称，便于维护和调用。
RabbitMqConfig.java：
- RabbitMQ的核心配置类。用于配置交换机、队列及队列与交换机的绑定关系。- 定义了两个DirectExchange（普通和延迟），两个Queue（普通和延迟/死信），以及它们的绑定关系。延迟队列设置了死信交换机和路由键，实现消息到期后转发到实际消费队列。
CancelOrderSender.java：
- 消息发送者。用于向订单延迟消息队列（mall.order.cancel.ttl）里发送消息。- 下单后，调用sendMessage方法向延迟队列发送消息，并设置延迟时间（如30秒），用于订单超时处理。
CancelOrderReceiver.java：
- 消息接收者。用于从取消订单的消息队列（mall.order.cancel）里接收消息。- 监听实际消费队列（mall.order.cancel），收到死信转发的消息后，调用订单服务取消订单。
OmsPortalOrderService.java 和 OmsPortalOrderServiceImpl.java：
- 订单服务接口及实现。- generateOrder方法下单后调用CancelOrderSender发送延迟取消消息，cancelOrder方法处理订单取消逻辑。
OrderParam.java：
- 下单参数的数据传输对象（DTO），用于接收前端下单请求的数据。
OmsPortalOrderController.java：
- 订单控制器，暴露下单接口，调用服务生成订单。
