1.Knife4j @ApiModelProperty position不生效--避坑
2.全面升级！码修一套基于Spring Boot 3+JDK17的码修实战项目！
3.神器 SpringDoc 横空出世！码修最适合 SpringBoot 的码修API文档工具来了
4.Java21 + SpringBoot3整合springdoc-openapi，自动生成在线接口文档，码修支持SpringSecurity和JWT认证方式
5.idea中使用maven的码修37的源码计算常用命令详解
6.一个注解干翻所有Controller

Knife4j @ApiModelProperty position不生效--避坑

       在项目中应用Knife4j-3.0.3，尽管官方文档说明基于swagger2-2..5，码修实际上应引用swagger2-3.0.0。码修

       在DTO上使用@ApiModelProperty注解时，码修UI默认会按照字段名的码修字母顺序展示。若需将关键字段前置，码修可尝试设定position属性。码修

       不料，码修发现position参数并未起效，码修查看官方GitHub的码修issue发现，此问题在版本2.4.9中已被修复，但仍有人反映此bug依旧存在。

       遍寻资料无果后，深入研究源码，在springfox.documentation.swagger2.mappers.CompatibilityModelMapper类中找到了问题所在。

       该类中的useModelV3配置默认为true，执行的排序逻辑使用了Comparator::naturalOrder，即按照字母顺序排列。而正确的排序逻辑应在后续分支的ModelMapper中，使用position与name的组合进行排序。

       修改配置

       在application.properties或application.yml文件中调整相关配置，确保Knife4j正确地应用排序规则，实现自定义展示顺序。

全面升级！一套基于Spring Boot 3+JDK的实战项目！

       最近对mall项目进行了全面升级，支持了Spring Boot 3和JDK。以下是mall项目的升级内容，包括依赖升级、框架用法升级以及运行部署的改动。Spring Boot 3版本的代码位于mall项目的dev-v3分支。

       mall项目简介：mall项目是一个基于SpringBoot、Vue和uni-app实现的如何改源码版权电商系统（Github标星K），采用Docker容器化部署。项目包括前台商城项目和后台管理系统，支持完整的订单流程，涵盖商品、订单、购物车、权限、优惠券、会员、支付等功能。

       项目演示：

       升级版本：项目中的依赖已经升级到最新主流版本，具体版本可参考下表。

       升级用法：在mall项目升级Spring Boot 3的过程中，部分框架的用法发生了变化。例如，生成API文档的库已从SpringFox迁移到SpringDoc，Spring Data Elasticsearch和Spring Security的用法也有所不同。以下将重点讲解这些升级的新用法。

       从SpringFox迁移到SpringDoc：由于之前使用的Swagger库为SpringFox，目前已不支持Spring Boot 3，因此已迁移到SpringDoc。

       Spring Data Elasticsearch新用法：Spring Data ES中基于ElasticsearchRepository的简单查询用法保持不变，但对于复杂查询，由于ElasticsearchRestTemplate类已被移除，需要使用ElasticsearchTemplate类来实现。

       Spring Security新用法：升级Spring Boot 3版本后，Spring Security的用法也有所变化。例如，某些实现动态权限的类已被弃用，Security配置改用函数式编程的方式。

       其他运行部署：由于Spring Boot 3最低要求是JDK，在Windows下运行项目时需要配置好项目的JDK版本，其他操作与之前版本相同。

       Linux：在打包应用的Docker镜像时，需要配置项目使用openjdk:。这可以在项目根目录下的pom.xml中修改docker-maven-plugin插件配置完成。

       由于镜像使用了openjdk:，kafka核心源码解读在打包镜像之前需要提前下载好openjdk的镜像。可以使用以下命令下载，其他操作与之前版本部署相同。

       总结：今天主要讲解了mall项目升级Spring Boot 3版本的一些注意点。项目源码地址：github.com/macrozheng/m...

神器 SpringDoc 横空出世！最适合 SpringBoot 的API文档工具来了

       之前在SpringBoot项目中，我一直在使用SpringFox提供的Swagger库。然而，当我浏览其官网时，发现已经有将近两年没有出新版本了。最近，当我升级到SpringBoot 2.6.x版本时，发现这个库的兼容性也越来越差，有些常用注解属性甚至被废弃了，而库中并没有提供替代方案。偶然间，我发现了一款名为SpringDoc的Swagger库，试用后发现效果非常不错，因此推荐给大家。

       SpringDoc是一款基于OpenAPI 3的API文档生成工具，可以与SpringBoot结合使用。在Github上，它已经获得了超过1.7K个Star，更新发布也相当频繁，可以说是一款比Swagger库更好用的工具。值得一提的是，SpringDoc不仅支持Spring WebMvc项目，还可以支持Spring WebFlux项目，甚至Spring Rest和Spring Native项目，功能非常强大。下面是一张SpringDoc的架构图。

       接下来，我将介绍SpringDoc的使用方法。我将以之前集成SpringFox的mall-tiny-swagger项目为例，将其改造为使用SpringDoc。

       首先，我们需要集成SpringDoc。springboot企业oa源码在pom.xml中添加它的依赖即可，开箱即用，无需任何配置。

       从SpringFox迁移结合SpringSecurity使用测试常用配置

       SpringDoc还有一些常用的配置可以了解，更多配置可以参考官方文档。

       总结

       在SpringFox的Swagger库好久不出新版的情况下，迁移到SpringDoc确实是一个更好的选择。今天我体验了一把SpringDoc，确实很好用，与之前熟悉的用法相似，学习成本极低。而且SpringDoc能支持WebFlux之类的项目，功能也更加强大，对于使用SpringFox觉得有些卡手的朋友来说，迁移到SpringDoc是一个不错的选择！

       参考资料项目源码地址：github.com/macrozheng/m...

       来源：mp.weixin.qq.com/s/scit...

Java + SpringBoot3整合springdoc-openapi，自动生成在线接口文档，支持SpringSecurity和JWT认证方式

       在Java 2.1与SpringBoot 3的项目开发中，我探索了一种方法，即通过整合springdoc-openapi来实现在线接口文档的自动生成，支持Spring Security和JWT认证。我的目标是打造一个适应多端且功能丰富的开发模板，方便开发者快速构建和扩展。

       本项目采用前后端分离模式，后端基于Java 2.1和SpringBoot 3，利用Spring Security、JWT、Spring Data JPA等技术进行开发，前端则提供了vue、angular、react、uniapp和微信小程序等多种技术栈。重点在于，如何利用OpenAPI规范来定义和展示API，这使得开发者无需深入了解源代码，就能理解API的功能和用法，极大地提高了开发效率。有源码怎么下载

       OpenAPI规范，即OAS，定义了RESTful API的通用标准，让开发者和工具能够理解和操作API。遵循OpenAPI，可以使用文档生成工具展示API，代码生成工具自动生成代码，甚至进行自动化测试。中国的OpenAPI规范中文版文档可参考这里。

       Swagger作为OpenAPI的实现工具，提供了组件如描述文件的维护，有助于更新文档和生成客户端和服务器端代码。Swagger的官方文档可在这里找到。

       Springfox是基于Swagger 2.x的API文档生成工具，它简化了Java开发者的工作，提供了注解支持和自动生成文档的功能。Springfox官方文档位于这里。

       然而，随着技术的发展，SpringDoc基于OpenAPI 3.0规范应运而生，成为了Spring Boot 2.4及以上版本的首选。相比Springfox，SpringDoc提供了更强大的扩展性和更好的社区支持。在SpringBoot 3中，推荐使用springdoc-openapi-ui进行集成。SpringDoc的官方文档可在这里查阅。

       在实践中，要实现这个功能，首先在pom.xml中引入springdoc-openapi-starter-webmvc-ui等相关依赖，然后配置application.yml，设定api-docs和swagger-ui的访问路径。如果项目有权限控制，需适当设置访问权限，如允许匿名访问api-docs和swagger-ui。在Controller类和实体类中，使用@Operation注解配合之前定义的security配置来指定认证方式。

       通过上述步骤，你可以生成符合规范的接口文档，方便团队协作和API的使用。后续我会不断更新学习心得，期待与大家一起进步。

idea中使用maven的常用命令详解

       Maven 常用命令详解

       使用 Maven 命令，可以高效地对项目进行清理、编译、测试、打包、安装，并部署到本地仓库或远程仓库。其中，几个常用的 Maven 命令包括：maven clean、maven compile、maven test、maven packet、maven install 和 maven deploy。

       一、Maven 常用命令及其作用

       1、maven clean：清理项目，删除 target 目录下的编译内容。

       2、maven compile：编译项目源代码。

       3、maven test：运行项目测试。

       4、maven packet：打包文件并存放到项目的 target 目录下，生成编译后的 class 文件。

       5、maven install：在本地仓库生成安装包，供其他项目引用，同时将打包后的文件存放到项目的 target 目录下。

       二、常用命令使用场景举例

       1、执行 mvn clean package 命令，依次执行了 clean、resources、compile、testResources、testCompile、test、jar（打包）等七个阶段。

       2、执行 mvn clean install 命令，依次执行了 clean、resources、compile、testResources、testCompile、test、jar（打包）、install 等八个阶段，完成项目编译、单元测试、打包，同时将 jar 包部署到本地 maven 仓库，但未部署到远程 maven 私服仓库。

       3、执行 mvn clean deploy 命令，依次执行了 clean、resources、compile、testResources、testCompile、test、jar（打包）、install、deploy 等九个阶段，完成项目编译、单元测试、打包，并将 jar 包部署到本地 maven 仓库和远程 maven 私服仓库。

       三、常见问题解答

       1、mvn clean install 和 mvn install 的区别：mvn install 可能得到的 jar 包为最新版本，除非手动修改 jar 包内容而不修改源代码；mvn clean install 生成最新 jar 包最保险。

       2、maven 跳过单元测试的方法：mvn package -Dmaven.test.skip=true 跳过单元测试及测试代码编译；mvn package -DskipTests 跳过单元测试但会继续编译，建议避免使用。

       3、测试环境部署脚本：mvn clean install -U -Dmaven.test.skip=true 跳过单元测试和测试代码编译；mvn clean install -U -DskipTests 跳过单元测试但会继续编译。

       4、查找 jar 包的引入配置：使用 mvn dependency:tree -Dverbose -Dincludes=要查询的内容，例如 mvn dependency:tree -Dverbose -Dincludes=io.springfox:jakarta.springfox-swagger2。

       Maven 命令提供了一种高效、灵活的方式来管理项目构建和依赖关系，适用于各种规模的项目开发。通过掌握这些命令及其应用场景，开发者可以显著提高项目构建和部署的效率。

一个注解干翻所有Controller

       日常开发中，繁重的Controller编写任务常常让开发者感到头疼。通常，公司会要求Controller仅承担参数解析和结果转换，避免业务逻辑混杂其中。然而，实际项目源码中，Controller中却往往包含着大量不应存在的业务逻辑。对此，是否应该依赖于Code Review来解决问题？在我看来，Controller本就不应存在。

       在对CommandService和QueryService进行封装时，我们借助定义接口的方式快速搭建了应用服务，大幅度提升了开发效率和代码质量。随后，通过构建在应用服务之上的Controller，将能力对外暴露。这是一个繁琐而缺乏技术含量的工作，对于这类重复性劳动，我的策略始终是“交由框架完成”。

       我们的目标是实现不编写Controller，同时保留Controller的功能。为了实现这一目标，首先需要配置依赖lego-starter和swagger相关依赖，并创建SpringFoxConfiguration启用Swagger。在浏览器输入指定地址，可以发现新增的两个Controller：command-dispatcher-controller和query-dispatcher-controller。command-dispatcher-controller主要负责CommanderService的Web暴露，支持业务操作如创建、更新等，query-dispatcher-controller则负责QueryService的Web暴露，用于执行业务查询操作，并支持RequestBody和RequestParam两种接入方式。

       在深入使用过程中，会遇到一些疑惑：serviceName和method参数从何获取？nativeRequest和nativeResponse又是何物？这两个接口如何使用？这些问题的解答并不直观，因为用户通常不会直接使用这两个处理器。

       对于Command控制器的使用，只需在OrderCommandService接口上添加@AutoRegisterWebController注解，即可将其对外暴露为Web端口。通过访问指定地址，可以看到OrderCommandService服务中的所有方法都在Controller中得到了体现。以create方法为例，可以发现与手写Controller的结构和功能基本一致。

       同样的，对于Query控制器，同样通过在OrderQueryService接口上添加@AutoRegisterWebController注解实现暴露。在访问指定地址并展开QueryByBody和QueryByParam方法后，可以清晰地看到与手写Controller相似的结构和功能。

       设计与扩展部分，整个设计可以分为两部分：统一Controller与Swagger集成。统一Controller部分提供QueryDispatcherController作为所有查询请求的入口，其核心架构涉及初始化和执行流程。与Swagger的集成则通过QueryServiceProvider实现，此组件依赖于QueryMethodRegistry中的QueryMethod信息，确保提供了完整的API文档。设计流程同样围绕QueryDispatcherController展开，确保与QueryServiceProvider的一致性。

       在项目信息部分，此解决方案来源于geekhalo，提供了一套高效、简洁的Controller替代方案，旨在简化开发流程，提升开发效率和代码质量。

SpringCloud微服务实战——搭建企业级开发框架（十九）：Gateway使用knife4j聚合微服务文档

       本篇内容聚焦于Spring Cloud Gateway网关如何集成knife4j，实现对所有Swagger微服务文档的聚合。首先，在gitegg-gateway项目中引入knife4j依赖，若无后端编码需求，仅引入swagger前端ui模块即可。随后，对配置文件进行修改，增加knife4j与Swagger2的配置。接下来，我们将重点介绍如何在微服务架构下，通过网关动态发现并聚合所有微服务文档的业务编码。

       在使用Spring Boot等单体架构集成swagger时，通常通过包路径进行业务分组，并在前端展示不同模块。然而，在微服务架构中，每个服务相当于一个独立的业务组。在Spring Cloud微服务架构下，通过重写提供分组接口的代码（如springfox-swagger提供的swagger-resource接口），可实现通过网关动态发现并聚合所有微服务的文档信息。具体实现代码如下：

       通过访问gitegg-gateway服务地址（/wmz/GitEg...的chapter-分支中。

       GitEgg-Cloud是基于SpringCloud整合搭建的企业级微服务应用开发框架，旨在提供一站式解决方案，帮助开发者高效构建微服务应用。项目开源地址如下：

       Gitee: /

       GitHub: /