本文相关视频: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”,