Knife4j：若依API文档用这个，界面美观功能强大

家人们，若依项目接口文档怎么管理？手写Swagger太丑？接口调试不方便？今天我给你推荐一个神器——Knife4j，保证你用完离不开。

这玩意儿能干啥？

Knife4j是Spring Boot生态中最美的API文档框架，专门解决这些问题：

1. 1. 接口文档自动生成：写完接口，文档自动出来
2. 2. 在线接口调试：不用Postman，直接在页面调
3. 3. 接口版本管理：文档变更历史一清二楚
4. 4. 权限控制：文档查看需要授权
5. 5. 离线文档导出：PDF/Markdown格式

简单说，Knife4j = Swagger + Postman + Markdown，一个工具全搞定。

若依开发中的痛点

家人们，若依项目里这些场景用Knife4j简直绝配：

接口调试效率提升300%，这不是吹的。

怎么用？

安装

<!-- Maven依赖 --><dependency>    <groupId>com.github.xiaoymin</groupId>    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>    <version>4.3.0</version></dependency>

若依配置

package com.ruoyi.framework.config;import io.swagger.annotations.ApiOperation;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.service.ApiInfo;import springfox.documentation.service.Contact;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration@EnableSwagger2public class Knife4jConfig {    @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                .select()                // 若依接口包路径                .apis(RequestHandlerSelectors.basePackage("com.ruoyi"))                // 有@ApiOperation注解的才生成文档                .apis(RequestHandlerSelectors.withMethodAnnotation(                        ApiOperation.class))                .paths(PathSelectors.any())                .build();    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .title("若依接口文档")                .description("RuoYi-Vue-Plus-Xiaowei API接口文档")                .contact(new Contact("小韦",                    "https://gitee.com/loveseaone",                    "xiaowei@email.com"))                .version("1.0.0")                .build();    }}

注解使用

@Api(tags = "用户管理")@RestController@RequestMapping("/system/user")public class SysUserController {    @ApiOperation("获取用户列表")    @GetMapping("/list")    public AjaxResult list(            @ApiParam("用户名")            @RequestParam(value = "userName", required = false) String userName,            @ApiParam("手机号码")            @RequestParam(value = "phonenumber", required = false) String phonenumber,            @ApiParam("状态")            @RequestParam(value = "status", required = false) String status) {        return AjaxResult.success(userService.selectUserList(new SysUser()));    }    @ApiOperation("新增用户")    @PostMapping    public AjaxResult add(            @ApiParam("用户信息")            @RequestBody SysUser user) {        return AjaxResult.success(userService.insertUser(user));    }    @ApiOperation("修改用户")    @PutMapping    public AjaxResult edit(            @ApiParam("用户信息")            @RequestBody SysUser user) {        return AjaxResult.success(userService.updateUser(user));    }    @ApiOperation("删除用户")    @DeleteMapping("/{userId}")    public AjaxResult remove(            @ApiParam("用户ID")            @PathVariable Long userId) {        return AjaxResult.success(userService.deleteUserById(userId));    }}

错误 vs 正确

❌ 错误写法：不分组，所有接口混在一起

// 一个Docket，所有接口return new Docket(DocumentationType.SWAGGER_2);

✅ 正确写法：分组展示，清晰明了

@Beanpublic Docket userApi() {    return new Docket(DocumentationType.SWAGGER_2)            .groupName("用户管理")            .select()            .apis(RequestHandlerSelectors.basePackage("com.ruoyi.system.controller"))            .build();}@Beanpublic Docket systemApi() {    return new Docket(DocumentationType.SWAGGER_2)            .groupName("系统管理")            .select()            .apis(RequestHandlerSelectors.basePackage("com.ruoyi.sys.controller"))            .build();}

应用场景

场景1：前后端联调

背景：若依项目前后端联调，接口参数经常对不上

方案：Knife4j在线调试

1. 后端写接口 → 文档自动生成2. 前端打开文档 → 查看接口定义3. 页面直接调试 → 确认返回数据4. 复制代码到前端 → 完成

效果：联调时间从2天→2小时，提升8倍

场景2：接口文档分享

背景：需要给第三方合作伙伴提供API文档

方案：Knife4j导出离线文档

# 在 Knife4j 文档页面点击"离线文档"# 选择导出格式：PDF/Markdown

效果：文档生成从1天→1分钟

场景3：接口权限控制

背景：内部接口文档不想让所有人看

方案：Knife4j + Spring Security

@Configurationpublic class SecurityConfig extends WebSecurityConfigurerAdapter {    @Override    protected void configure(HttpSecurity http) throws Exception {        http            .authorizeRequests()            .antMatchers("/swagger-ui.html", "/doc.html").authenticated()            .anyRequest().permitAll();    }}

效果：文档泄露风险降低90%

项目亮点

踩坑提示

问题1：文档打不开

第一优先排查：检查是否引入正确依赖

<!-- 错误：旧版本 --><dependency>    <groupId>com.github.xiaoymin</groupId>    <artifactId>knife4j-spring-boot-starter</artifactId>    <version>3.0.2</version></dependency><!-- 正确：新版本 --><dependency>    <groupId>com.github.xiaoymin</groupId>    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>    <version>4.3.0</version></dependency>

问题2：接口没显示

第一优先排查：检查包路径是否正确

// 必须是你的Controller所在包.apis(RequestHandlerSelectors.basePackage("com.ruoyi"))

问题3：参数注解不生效

第一优先排查：是否添加了swagger注解

// 必须添加的注解@ApiOperation("接口说明")@GetMapping("/test")public void test(@ApiParam("参数说明") String param) {}

总结

Knife4j真的香：

• • 界面美观，比Swagger原生界面好看10倍
• • 功能强大，文档+调试+导出全搞定
• • 集成简单，Spring Boot零配置
• • 持续维护，版本迭代快

家人们，若依项目用Knife4j，接口文档不再烦。赶紧用起来！

GitHub：https://github.com/xiaoymin/knife4j文档：https://doc.xiaoymin.cn