RuoYi-Vue-fast后端API文档管理：Knife4j增强Swagger实践-优快云博客

RuoYi-Vue-fast后端API文档管理：Knife4j增强Swagger实践

【免费下载链接】RuoYi-Vue-fast :tada: (RuoYi)官方仓库基于SpringBoot，Spring Security，JWT，Vue & Element 的前后端分离权限管理系统项目地址: https://gitcode.com/GitHub_Trending/ru/RuoYi-Vue-fast

你是否还在为后端API文档的可读性差、调试困难而烦恼？是否希望有一款工具能让API文档既专业又易用？本文将详细介绍如何在RuoYi-Vue-fast项目中集成Knife4j来增强Swagger，打造高效、美观的API文档管理系统。读完本文，你将掌握Knife4j的集成步骤、配置方法以及高级功能的使用，让API文档管理变得轻松简单。

为什么选择Knife4j增强Swagger

在现代后端开发中，API文档是前后端协作的重要桥梁。Swagger作为一款主流的API文档生成工具，虽然功能强大，但在用户体验和界面美观度上还有提升空间。Knife4j是一款基于Swagger的增强工具，它在Swagger的基础上提供了更友好的UI界面、更丰富的功能，如接口排序、在线调试、文档导出等，极大地提升了API文档的使用体验。

RuoYi-Vue-fast项目默认集成了Swagger，其相关配置可以在src/main/java/com/ruoyi/framework/config/SwaggerConfig.java中找到。该配置类通过@Configuration注解声明，使用@Bean注解创建Docket对象来配置Swagger的基本信息和扫描规则。

Knife4j集成步骤

添加Knife4j依赖

要在RuoYi-Vue-fast项目中集成Knife4j，首先需要在pom.xml文件中添加Knife4j的依赖。打开pom.xml文件，在<dependencies>标签内添加以下依赖：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

这里使用的是Knife4j的3.0.3版本，你可以根据项目需求选择合适的版本。添加依赖后，Maven会自动下载并导入相关的Jar包。

配置SwaggerConfig

接下来需要修改Swagger的配置类，以启用Knife4j的增强功能。打开src/main/java/com/ruoyi/framework/config/SwaggerConfig.java文件，在Docket对象的配置中添加Knife4j的相关设置。

在createRestApi方法中，添加以下代码：

.enable(enabled)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build()
.securitySchemes(securitySchemes())
.securityContexts(securityContexts())
.pathMapping(pathMapping)
.extensions(Collections.singletonList(new OpenApiExtensionResolver("knife4j", new Resource[]{})))

其中，OpenApiExtensionResolver是Knife4j提供的扩展解析器，用于加载Knife4j的增强配置。

配置资源处理器

为了让Knife4j的静态资源能够被正确访问，需要在资源配置类中添加相应的资源处理器。打开src/main/java/com/ruoyi/framework/config/ResourcesConfig.java文件，在addResourceHandlers方法中添加以下代码：

/** knife4j配置 */
registry.addResourceHandler("/doc.html")
        .addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
        .addResourceLocations("classpath:/META-INF/resources/webjars/");

这些配置将Knife4j的UI页面和相关静态资源映射到对应的URL路径，确保页面能够正常访问。

配置安全放行

由于RuoYi-Vue-fast项目使用了Spring Security进行权限控制，需要在安全配置中放行Knife4j和Swagger的相关路径，以确保未登录用户也能访问API文档。打开src/main/java/com/ruoyi/framework/config/SecurityConfig.java文件，在configure方法的authorizeRequests部分添加以下代码：

.antMatchers("/doc.html", "/webjars/**", "/swagger-resources/**", "/v3/api-docs/**").permitAll()

这样，用户就可以直接访问Knife4j的API文档页面了。

Knife4j高级功能配置

接口排序

Knife4j支持对接口进行排序，使文档更加清晰有序。在Swagger的@Api注解中，可以通过position属性来指定接口的排序位置。例如：

@Api(tags = "用户管理", position = 1)
@RestController
@RequestMapping("/system/user")
public class SysUserController extends BaseController {
    // ...
}

在线调试

Knife4j提供了强大的在线调试功能，支持直接在文档页面发送请求并查看响应结果。在接口方法上添加@ApiOperation注解，即可在文档页面显示调试按钮。例如：

@ApiOperation("获取用户列表")
@GetMapping("/list")
public TableDataInfo list(SysUser user) {
    startPage();
    List<SysUser> list = userService.selectUserList(user);
    return getDataTable(list);
}

文档导出

Knife4j支持将API文档导出为Markdown、HTML、PDF等多种格式，方便离线查阅和分享。在文档页面的右上角，点击"文档下载"按钮，即可选择需要导出的格式。

接口分组

对于大型项目，接口数量较多时，可以使用Knife4j的接口分组功能，将接口按照模块进行分类。在SwaggerConfig类中，可以创建多个Docket对象，每个Docket对象对应一个接口分组。例如：

@Bean
public Docket createUserApi() {
    return new Docket(DocumentationType.OAS_30)
            .groupName("用户管理")
            .enable(enabled)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.ruoyi.project.system.controller"))
            .paths(PathSelectors.any())
            .build();
}

@Bean
public Docket createMenuApi() {
    return new Docket(DocumentationType.OAS_30)
            .groupName("菜单管理")
            .enable(enabled)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.ruoyi.project.system.controller"))
            .paths(PathSelectors.ant("/system/menu/**"))
            .build();
}

效果展示

完成以上配置后，启动项目，访问http://localhost:8080/doc.html即可打开Knife4j的API文档页面。页面左侧为接口列表，右侧为接口详情，包括请求参数、响应结果、示例代码等信息。

你可以在页面中直接进行接口调试，填写请求参数后点击"发送"按钮，即可查看服务器返回的响应结果。此外，还可以通过页面顶部的搜索框快速查找需要的接口。

总结

通过本文的介绍，我们了解了如何在RuoYi-Vue-fast项目中集成Knife4j来增强Swagger，实现了API文档的美观化和功能增强。Knife4j提供的丰富功能，如接口排序、在线调试、文档导出等，极大地提升了API文档的实用性和易用性，有助于提高前后端协作的效率。

如果你想进一步了解Knife4j的更多功能，可以参考Knife4j的官方文档。同时，RuoYi-Vue-fast项目的其他相关配置和代码可以在项目的源代码中找到，例如：

系统配置类：src/main/java/com/ruoyi/framework/config/RuoYiConfig.java
安全服务类：src/main/java/com/ruoyi/framework/security/service/
控制器示例：src/main/java/com/ruoyi/project/tool/swagger/TestController.java

希望本文对你在RuoYi-Vue-fast项目中使用Knife4j增强Swagger有所帮助！如果你有任何问题或建议，欢迎在项目的issue中提出。

点赞、收藏、关注三连，下期我们将介绍RuoYi-Vue-fast项目的其他高级功能，敬请期待！

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考