做 SpringBoot 开发，API 文档工具是刚需。SwaggerUI 虽常用，但用久了全是槽点：界面老、找接口难、改样式麻烦…… 今天给大家安利一款更好用的工具 ——Knife4j，堪称 SwaggerUI 的 “升级版”，用一次就回不去。

一、SwaggerUI 的坑，你中了几个？

1. 交互太烂

切换接口要整页刷新，接口多了翻到手酸；返回的 JSON 堆成一团，嵌套几层就看不清，还不能折叠；想找个接口？没搜索功能，只能慢慢拖滚动条。

2. 定制难上天

想加个公司 logo？得改源码模板，重新打包；想加测试环境切换、权限控制？基本没戏，完全不符合 SpringBoot”零配置” 的方便。

3. 安全和性能差

生产环境忘关，接口信息直接暴露；接口超 100 个，打开文档要等 3-5 秒，由于它一次性加载所有数据。

二、Knife4j：SwaggerUI 的完美替代

Knife4j 基于 Swagger 开发，原来的注解照样用，不用重新学，却解决了所有痛点。

核心优势一眼看穿

功能	Knife4j	SwaggerUI
界面	现代 Vue+Element UI，清爽流畅	老旧 HTML+CSS，死板难看
找接口	支持搜索、筛选，秒定位	无搜索，手动翻
看结果	JSON 可折叠、复制、格式化	纯文本堆一起，乱糟糟
改样式	30 + 配置参数，轻松搞定	改源码，新手勿碰
安全性	可设密码，生产环境能直接关	无保护，易泄密
加载速度	100 个接口 1 秒加载完	3 秒以上

这些实用功能绝了

• 保存测试环境地址和 Token，切换环境不用重复输参数。

• 测试结果能导出成 Postman 格式，前端拿过去就能用。

• 支持 Mock 数据，后端没写完接口，前端也能先开发。

三、SpringBoot 集成 Knife4j，3 步搞定

1. 加依赖

删了原来的 Swagger 依赖，加这个：

<dependency>

<groupId>com.github.xiaoymin</groupId>

<artifactId>knife4j-spring-boot-starter</artifactId>

<version>3.0.3</version>

</dependency>

2. 写配置

配置类简单设置下，还能加全局 Token：

@Configuration

@EnableKnife4j

@EnableOpenApi

public class Knife4jConfig {

@Bean

public Docket api() {

return new Docket(DocumentationType.OAS_30)

.apiInfo(new ApiInfoBuilder()

.title(“用户API文档”)

.version(“1.0”)

.build())

.select()

.apis(RequestHandlerSelectors.basePackage(“com.example.controller”))

.paths(PathSelectors.any())

.build();

}

}

3. 接口加注解

原来的 Swagger 注解能用，新增 @ApiOperationSupport 加作者、排序：

@RestController

@Api(tags = “用户接口”)

public class UserController {

@PostMapping(“/login”)

@ApiOperation(“登录”)

@ApiOperationSupport(author = “张三”, order = 1)

public Result login(@RequestBody LoginDTO dto) {

// 业务逻辑

}

}

启动后访问
http://localhost:8080/doc.html，新界面立马能用。

四、从 SwaggerUI 迁移，超简单

1. 换依赖：删 Swagger，加 Knife4j。

2. 改配置：@EnableSwagger2 换成 @EnableKnife4j。

3. 换地址：从 /swagger-ui.html 改成 /doc.html，其他啥都不用动。

五、生产环境用着放心

怕泄密？加配置关文档或设密码：

knife4j:

production: true # 直接关

# 或设密码

basic:

enable: true

username: admin

password: 123456

接口多加载慢？开启缓存 + 分组：

knife4j:

cache:

enable: true

group:

– groupName: 用户模块

apiRule: com.example.user.controller.*

总结

接口多、前后端协作频繁？选 Knife4j 准没错，界面好、功能全，还不用重新学。小项目 SwaggerUI 可能够，但中大型项目用 Knife4j，效率直接翻倍。

你用 SwaggerUI 踩过哪些坑？评论区聊聊～

#SpringBoot #API 文档 #开发工具 #编程技巧 #后端开发