在若依Ruoyi-Vue中集成Knife4j实现Swagger文档增强

本文相关视频：https://www.bilibili.com/video/BV1Fi4y1q74p?p=49&vd_source=2894aa0e46c09ba98269f266128b6c6e

一、Knife4j介绍

Knife4j，原名Springfox-Swagger-UI，是为Swagger接口文档提供增强UI展示效果的工具，它在原生Swagger-UI基础上进行了大量功能扩展与优化。Knife4j凭借其友好的界面、丰富的交互功能、强大的个性化定制能力，成为众多开发者首选的API文档管理工具。

集成Knife4j后，即可在若依-Ruoyi-Vue项目中体验到Swagger文档的诸多增强特性，提升API文档的实用性和易用性。以下列举部分典型应用场景：

1. 界面优化

Knife4j提供了更美观、更直观的UI界面，包括响应示例折叠/展开、在线调试、模型树结构展示等功能，极大改善了开发者查阅和测试API的体验。

2. 动态文档

支持实时更新接口文档，无需手动刷新页面。当代码发生变化时，文档内容会自动同步更新，确保文档与实际代码始终保持一致。

3. 接口排序与过滤

允许用户按照接口分组、标签、路径等多种方式对API进行排序和筛选，方便快速定位所需接口。

4. 扩展功能

提供丰富的扩展功能，如全局参数设置、自定义全局响应示例、离线文档导出、个性化设置保存等，满足不同团队的个性化需求。

5. OAuth2支持

无缝集成OAuth2认证，支持多种授权类型，便于在安全环境下调试API。

二、集成步骤

1. 添加依赖

ruoyi-admin\pom.xml模块添加整合依赖

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

引用knife4j-spring-boot-starter依赖，项目中的swagger依赖可以删除。

2. 定义Swagger资源

和swagger一样，使用@EnableSwagger2WebMvc或@EnableSwagger2注解启用Swagger，并通过Docket配置Swagger资源：

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.ruoyi.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("若依-Ruoyi API文档")
                .description("详细的接口文档说明")
                .version("1.0.0")
                .contact(new Contact("联系人", "https://ruoyi.vip/", "邮箱"))
                .build();
    }
}

3. Controller层注解

在Controller类或方法上使用Swagger相关的注解（如@Api, @ApiOperation, @ApiParam等），为每个接口提供详细的描述信息：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;

@Api(tags = "用户管理接口")
@RestController
@RequestMapping("/api/user")
public class UserController {

    @ApiOperation("获取用户信息")
    @GetMapping("/{id}")
    public User getUser(@ApiParam(name = "id", value = "用户ID", required = true) @PathVariable Long id) {
        // 实现代码...
    }
}

4. 修改前端跳转地址

修改ry-ui\views\tool\swagger\index.vue跳转地址

src: process.env.VUE_APP_BASE_API + “/doc.html”,