SpringBoot3.0+项目使用Knife4j集成Swagger接口文档教程
一、项目简介
本教程将指导你在 Spring Boot 3.0+ 项目中集成 SpringDoc OpenAPI 3 和 Knife4j，生成美观的 API 接口文档。
Knife4j官方教程
二、环境要求
JDK 17+
Spring Boot 3.0+
Maven 3.6+
三、详细步骤
1. 添加依赖
在pom.xml中添加以下依赖：
<!-- SpringDoc OpenAPI 3 核心依赖 --> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.8.16</version> </dependency> <!-- Knife4j 增强UI界面 --> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId> <version>4.4.0</version> </dependency>注意：在Maven仓库查找最新版依赖
2. 配置 application.yaml
在配置文件中添加以下配置：
# springdoc-openapi项目配置 springdoc: swagger-ui: path: /swagger-ui.html tags-sorter: alpha operations-sorter: alpha api-docs: path: /v3/api-docs group-configs: - group: 'default' paths-to-match: '/**' packages-to-scan: com.example.org.controller # knife4j的增强配置 knife4j: enable: true setting: language: zh_cn3. 访问地址
ip:port写自己的项目后端接口
Knife4j 文档地址:
http://ip:port/doc.html原生 Swagger UI:
http://ip:port/swagger-ui/index.htmlOpenAPI JSON:
http://ip:port/v3/api-docsOpenAPI YAML:
http://ip:port/v3/api-docs.yaml
4.注解使用
Knife4j 常用注解
注解名称 | 作用位置 | 参数示例 | 功能说明 |
|---|---|---|---|
@Tag | 控制器类 |
| 接口分组标签 |
@Operation | 方法 |
| 接口基本描述 |
@Parameter | 参数 |
| 单个参数描述 |
@Parameters | 方法 |
| 多个参数描述 |
@Schema | 实体类/字段 |
| 模型/字段描述 |
@ApiResponse | 方法 |
| 单个响应描述 |
@ApiResponses | 方法 |
| 多个响应描述 |
@Hidden | 类/方法/字段 |
| 隐藏接口/字段 |
@ExampleObject | 方法参数 |
| 示例数据 |
@Content | 响应 |
| 响应内容类型 |
快速使用示例：
@RestController @Tag(name = "用户接口") // 分组标签 class UserController { @PostMapping("/user") @Operation(summary = "创建用户") // 接口描述 @Parameters({ @Parameter(name = "token", in = ParameterIn.HEADER, required = true) // 参数 }) @ApiResponses({ @ApiResponse(responseCode = "200", description = "成功") // 响应 }) public UserDTO create(@RequestBody UserVO vo) { return userService.create(vo); } } @Data class UserVO { @Schema(description = "用户名", example = "张三", required = true) // 字段 private String name; @Hidden // 隐藏字段 private String password; }