若依集成 Knife4j

### 若依框架集成 Knife4j 实现 API 文档增强 #### 集成背景 Knife4j 是一款基于 Swagger 的 API 文档生成工具，专注于为 Java 开发者提供更优质的接口文档管理和展示功能[^1]。通过在若依 (RuoYi) 框架中集成 Knife4j，可以显著提升 API 文档的实用性和易用性[^2]。 #### 准备工作 确保项目已具备以下条件： - 已经搭建好 RuoYi-Vue 或其他版本的基础环境。 - Maven 构建工具可用。 - Spring Boot 和 Spring Cloud 版本兼容 Knife4j 所需最低版本。 #### 添加依赖 在项目的 `pom.xml` 文件中添加 Knife4j 的相关依赖： ```xml <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>最新稳定版号</version> </dependency> ``` 注意：具体版本号可以根据实际需求选择最新的稳定版本。 #### 修改配置文件 编辑 `application.yml` 或 `application.properties` 文件，加入 Knife4j 的基础配置项： ```yaml spring: swagger: enabled: true server: servlet: context-path: / knife4j: enable: true setting: enableSwaggerModels: false ``` 上述配置启用了 Knife4j 并关闭了默认的模型显示选项[^3]。 #### 创建配置类 创建一个新的配置类用于初始化 Knife4j 功能： ```java import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.service.ApiInfo; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; @Configuration @EnableKnife4j public class Knife4jConfig { @Bean(value = "defaultApi2") public Docket defaultApi2() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("若依系统API文档") .description("更多请关注http://www.ruoyi.vip") .termsOfServiceUrl("") .contact(new Contact("若依", "", "")) .version("1.0") .build(); } } ``` 此代码片段实现了对 Knife4j 的基本支持并设置了 API 文档的相关元数据。 #### 解决常见问题 如果按照以上步骤操作后仍然遇到诸如 Whitelabel Error Page 页面提示或 404 错误等问题，则可能需要进一步排查原因。以下是几种常见的解决方案： - **删除旧有配置**：移除原有的 Swagger 相关配置文件内容，重新整理后再逐步添加新设置。 - **检查路径冲突**：确认是否存在与其他模块路径重复的情况，并调整上下文根目录地址。 - **升级依赖库**：确保所使用的第三方组件均为最新版本以减少潜在不兼容风险[^4]。 #### 测试验证 完成上述所有步骤之后启动应用程序，在浏览器输入如下 URL 地址访问新增加的功能界面： ``` http://localhost:{port}/doc.html ``` 此时应该可以看到由 Knife4j 提供的一个更加美观且交互性强的新版 API 文档页面。 ---