Knife4j可直接替换或增强原生Swagger，提升文档清晰度、可调试性与易分享性；需使用knife4j-openapi3-jakarta-spring-boot-starter依赖，配置@EnableOpenApi，并通过@Tag、@Operation等注解完善描述，按业务分组展示，生产环境注意开关控制与反向代理路径透传。
直接用 Knife4j 替换或增强原生 Swagger，就能让接口文档变清晰、可调试、易分享。它不改变你的 REST 接口逻辑，只在文档层做提升——界面更直观、分组更合理、注解更到位、导出更灵活。
选对依赖和配置方式
SpringBoot 3 项目必须用 Jakarta 兼容版本，否则启动报错或注解失效：
- 删掉旧的
springfox-swagger2或swagger-ui相关依赖 - 引入正确组合：
knife4j-openapi3-jakarta-spring-boot-starter（核心）springdoc-openapi-starter-webmvc-ui（底层 OpenAPI3 支持） - 配置类用
@EnableOpenApi，不是@EnableSwagger2或@EnableKnife4j（后者已过时）
让接口描述真正有用
光有路径和参数名不够，要让前端一眼看懂怎么调：
Alibabacloud Sdk Client Initialization For Java
下载
在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。
- 在 Controller 类上加
@Tag(name = "用户管理", description = "登录、注册、信息查询") - 在每个方法上加
@Operation(summary = "手机号登录", description = "返回 JWT token 和用户基础信息") - 参数用
@Parameter(description = "6~16位密码，需含数字和字母")或@Schema(description = "邮箱格式，必填")标在 DTO 字段上 - 避免只写
@ApiParam这类老式注解，SpringBoot 3 下基本不识别
按业务分组展示，别堆成一张大表
所有接口挤在“default”里，查起来费劲。用多 Docket 实现模块化：
- 每个
@Bean方法返回一个OpenAPI实例（SpringBoot 3）或Docket（旧版），并指定.groupName("订单中心") - 扫描路径严格限定：
.apis(RequestHandlerSelectors.basePackage("com.xxx.order.controller")) - UI 右上角会自动出现下拉菜单，切换不同模块文档，互不干扰
- 如果某模块暂时不想暴露，直接注释掉对应
@Bean即可，无需改代码
上线前检查几项关键设置
本地能看不等于线上可用，尤其涉及外网访问时：
- 确认
knife4j.enable=true在生产环境配置中没被覆盖或设为 false - 若用 Nginx 反向代理，确保
/v3/api-docs和/doc.html路径被正确透传（不要丢 query 参数） - 敏感环境（如正式服）建议关闭 Knife4j：通过 profile 控制，比如只在
dev和test激活 - 导出离线文档时，优先选 HTML 格式——加载快、无依赖、支持搜索，比 Markdown 更实用
