SpringBoot中使用Knife4j生成接口文档的示例详解
作者：超级小忍
前言
Knife4j 是一个基于 Swagger 的增强 UI 实现，主要用于为 Spring Boot 应用程序生成 API 接口文档。它不仅支持标准的 OpenAPI 规范，还提供了更加友好的界面和强大的功能。本文将详细介绍如何在 Spring Boot 中集成 Knife4j，并通过不同注解来生成清晰的接口文档。同时，我们也会比较 Spring Boot 2.x 和 Spring Boot 3.x 版本中使用 Knife4j 的差异。
一、Knife4j 简介
Knife4j 是 Swagger 的增强工具包，其核心特性包括：
- 支持 OpenAPI 2.0 / 3.0
- 提供更美观的 UI 界面
- 支持接口调试
- 支持分组管理
- 支持离线文档导出（HTML/PDF）
二、Spring Boot 集成 Knife4j
1. 添加依赖
Spring Boot 2.x（基于 Swagger 2）
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.9</version>
</dependency>
Spring Boot 3.x（基于 Swagger 3/OpenAPI 3.0）
从 Spring Boot 3.x 开始，官方全面转向 Jakarta EE 9+，包名由 javax 变更为 jakarta，因此需要使用适配 Jakarta 的版本。
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.5.0</version>
</dependency>
注意：Spring Boot 3.x 使用的是 OpenAPI 3.0，而不再是 Swagger 2。
2. 启用 Knife4j
创建配置类或直接在主启动类上添加注解启用 Knife4j。
Spring Boot 2.x
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
@EnableKnife4j
public class SwaggerConfig {
}
Spring Boot 3.x
import com.github.xiaoymin.knife4j.core.constants.Knife4jOpenApi3UrlConstant;
import com.github.xiaoymin.knife4j.openap3.configuration.OpenApi3Configuration;
import com.github.xiaoymin.knife4j.spring.boot.extension.OpenApi3ExtensionResolver;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class SwaggerConfig {
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info()
.title("Spring Boot 3.x Knife4j 示例")
.version("1.0")
.description("基于 OpenAPI 3.0 的接口文档"));
}
// 必须加上这个 Bean 才能启用 Knife4j 的扩展功能
@Bean
public OpenApi3ExtensionResolver openApi3ExtensionResolver() {
return new OpenApi3ExtensionResolver();
}
}
三、常用注解说明
1. 控制器级别注解
| 注解 | 描述 | Spring Boot 版本 |
|---|---|---|
| @Api(tags = "用户管理") | 用于类上，表示该控制器对应的功能模块名称 | 2.x & 3.x |
| @RequestMapping("/user") | 定义请求路径 | 通用 |
示例：
@RestController
@RequestMapping("/user")
@Api(tags = "用户管理")
public class UserController {
}
2. 方法级别注解
| 注解 | 描述 | Spring Boot 版本 |
|---|---|---|
| @ApiOperation(value = "获取用户列表", notes = "返回所有用户信息") | 描述方法用途 | 2.x |
| @Operation(summary = "获取用户列表", description = "返回所有用户信息") | OpenAPI 3.0 替代方案 | 3.x |
| @ApiImplicitParams({@ApiImplicitParam(name = "pageNum", value = "页码", required = true, dataType = "int")}) | 描述参数（适用于非实体对象参数） | 2.x |
| @Parameters({@Parameter(name = "pageNum", description = "页码", required = true)}) | OpenAPI 3.0 替代方案 | 3.x |
示例：
Spring Boot 2.x
@GetMapping("/list")
@ApiOperation(value = "获取用户列表", notes = "返回所有用户信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "pageNum", value = "页码", required = true, dataType = "int"),
@ApiImplicitParam(name = "pageSize", value = "每页数量", required = false, dataType = "int")
})
public List<User> listUsers(int pageNum, int pageSize) {
return userService.list(pageNum, pageSize);
}
Spring Boot 3.x
@GetMapping("/list")
@Operation(summary = "获取用户列表", description = "返回所有用户信息")
@Parameters({
@Parameter(name = "pageNum", description = "页码", required = true),
@Parameter(name = "pageSize", description = "每页数量", required = false)
})
public List<User> listUsers(int pageNum, int pageSize) {
return userService.list(pageNum, pageSize);
}
3. 参数对象字段注解
当使用实体类接收参数时，可以对字段进行描述。
| 注解 | 描述 | Spring Boot 版本 |
|---|---|---|
| @ApiModelProperty(value = "用户名", example = "admin") | 描述字段含义及示例值 | 2.x |
| @Schema(description = "用户名", example = "admin") | OpenAPI 3.0 替代方案 | 3.x |
示例：
public class UserDTO {
@Schema(description = "用户名", example = "admin")
private String username;
@Schema(description = "密码", example = "123456")
private String password;
}
四、访问 Knife4j 文档页面
启动项目后，访问以下地址查看接口文档：
Spring Boot 2.x：http://localhost:8080/knife4j-ui.html
Spring Boot 3.x：http://localhost:8080/doc.html
五、常见问题与注意事项
1. Spring Boot 3.x 下无法访问/doc.html
请确保你使用了正确的 Starter 包（带 openapi3-jakarta 字样），并且正确配置了 OpenAPI Bean。
2. 参数没有显示注释
确保你在实体类字段上使用了 @Schema 或 @ApiModelProperty 注解，并且开启了相应的自动扫描。
3. 多个接口分组展示
可以通过 Docket（Spring Boot 2.x）或 OpenAPI + 分组配置（Spring Boot 3.x）实现多组接口文档。
六、总结
| 功能 | Spring Boot 2.x | Spring Boot 3.x |
|---|---|---|
| 依赖包 | knife4j-spring-boot-starter | knife4j-openapi3-jakarta-spring-boot-starter |
| 核心注解 | @Api、@ApiOperation、@ApiImplicitParam、@ApiModelProperty | @Tag、@Operation、@Parameter、@Schema |
| 访问地址 | /knife4j-ui.html | /doc.html |
| 默认协议 | Swagger 2.0 | OpenAPI 3.0 |
以上就是SpringBoot中使用Knife4j生成接口文档的示例详解的详细内容，更多关于SpringBoot Knife4j生成接口文档的资料请关注脚本之家其它相关文章！