当前位置：首页 > backend >正文

Knife4j快速入门

backend 2025/7/15 21:36:12

Knife4j 介绍

Knife4j 是一个为 Java 开发人员设计的接口文档生成工具，它基于 Swagger 规范，能够自动从代码中提取接口信息，并生成漂亮的、可交互的 API 文档。Knife4j 可以与 Spring Boot、Spring MVC 等 Java 框架无缝集成，帮助开发者快速生成和维护 API 文档。

以下是 Knife4j 的一些主要特点：

• 自动生成文档：Knife4j 能够自动从代码中提取接口信息，包括接口地址、请求方法、参数、响应等，无需手动编写文档。

• 可交互的文档：生成的文档是可交互的，用户可以直接在文档页面上进行接口调用，查看请求参数和响应结果。

• 支持 Swagger 2.0：Knife4j 遵循 Swagger 2.0 规范，可以与 Swagger 编辑器等工具兼容。

• 丰富的扩展性：Knife4j 提供了丰富的扩展点，允许开发者自定义文档的样式、内容等。

• 集成简单：Knife4j 可以很容易地集成到现有的 Java 项目中，支持 Maven 和 Gradle 构建工具。

• 支持多种语言：Knife4j 生成的文档支持多种语言，方便不同语言背景的开发者使用。

• 安全性：Knife4j 支持接口的安全认证，如 OAuth2、Basic Auth 等，确保文档的安全性。

Knife4j 通常用于后端服务的开发，帮助开发者和前端开发者、测试人员等更好地理解和使用后端接口。通过 Knife4j，可以提高开发效率，减少文档维护的工作量，同时也提高了团队之间的协作效率。

与Spring Boot集成

创建一个Spring Boot项目

在这里插入图片描述

导入MAVEN依赖

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>3.5.3</version><relativePath/> <!-- lookup parent from repository --></parent><groupId>com.nie</groupId><artifactId>hello-knife4j</artifactId><version>0.0.1-SNAPSHOT</version><name>hello-knife4j</name><description>hello-knife4j</description><url/><licenses><license/></licenses><developers><developer/></developers><scm><connection/><developerConnection/><tag/><url/></scm><properties><java.version>17</java.version></properties><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><optional>true</optional></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.3.0</version></dependency></dependencies><build><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><configuration><annotationProcessorPaths><path><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId></path></annotationProcessorPaths></configuration></plugin><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId><configuration><excludes><exclude><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId></exclude></excludes></configuration></plugin></plugins></build></project>

创建配置类

package com.nie.helloknife4j.config;import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;@Configuration
public class Knife4jConfiguration {@Beanpublic OpenAPI openAPI() {return new OpenAPI().info(new Info().title("hello-knife4j项目API").version("1.0").description("hello-knife4j项目的接口文档"));}@Beanpublic GroupedOpenApi userAPI() {return GroupedOpenApi.builder().group("用户信息管理").pathsToMatch("/user/**").build();}@Beanpublic GroupedOpenApi systemAPI() {return GroupedOpenApi.builder().group("产品信息管理").pathsToMatch("/product/**").build();}
}

启动项目

访问:http://localhost:8080/doc.html
在这里插入图片描述

编写测试接口

编写实体类

package com.nie.helloknife4j.entity;import lombok.Data;@Data
public class User {private Integer id;private String name;private String sex;
}

编写Controller层

package com.nie.helloknife4j.controller;import com.nie.helloknife4j.entity.User;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;@RequestMapping("/user")
@RestController
public class UserController {@GetMapping("/getById")public User getById(@RequestParam Integer id) {User user = new User();user.setId( id);user.setName("二狗子");user.setSex("男");return user;}
}

再次访问:http://localhost:8080/doc.html
在这里插入图片描述
可以看到我们编写的测试接口就已经在里面了

调试

我们还可以直接在里面调试
在这里插入图片描述

常用注解

@Tag用于标注在Controller层上面
例如:@Tag(name = "用户信息管理")

@RequestMapping("/user")
@RestController
@Tag(name = "用户信息管理")
public class UserController {

@Operation用于标注在方法上面
例如

    @GetMapping("/getById")@Operation(summary = "根据id查询用户信息")public User getById(@RequestParam Integer id) {User user = new User();user.setId( id);user.setName("二狗子");user.setSex("男");return user;}

@Parameter 用来加到参数上面
例如

    @GetMapping("/getById")@Operation(summary = "根据id查询用户信息")public User getById(@Parameter(description = "用户id") @RequestParam Integer id) {User user = new User();user.setId( id);user.setName("二狗子");user.setSex("男");return user;}