Knife4j 快速入门：集Swagger2 和 OpenAPI3 为一体的增强解决方案

Knife4j 快速入门：5分钟搞定SpringBoot接口文档

Knife4j是基于Swagger/OpenAPI规范 的增强版接口文档工具，自带高颜值中文UI、在线调试、文档导出等能力，SpringBoot项目零门槛集成，彻底告别手写文档。

官网链接https://doc.xiaominfo.com/

一、Knife4j 与 Swagger 是什么关系

Swagger/OpenAPI：接口文档规范，负责定义接口结构
Knife4j ：在Swagger基础上做增强，配置兼容、注解通用，只换UI和功能
访问地址
- 原生Swagger：http://ip:port/swagger-ui.html
- Knife4j增强版：http://ip:port/doc.html

二、环境要求

SpringBoot 2/3 均可
JDK 8+（SB2）/ JDK 17+（SB3）
Maven/Gradle

三、一步一步集成

1. 引入依赖（按你的SpringBoot版本选）

SpringBoot 3 + OpenAPI3（推荐）

XML 复制代码

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>

SpringBoot 2 + OpenAPI2

XML 复制代码

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

SpringBoot 2 + OpenAPI3

XML 复制代码

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

2. application.yml 核心配置

YAML 复制代码

# springdoc-openapi 基础配置（Swagger内核）
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.你的包名.controller

# Knife4j 增强配置
knife4j:
  enable: true # 开启增强
  setting:
    language: zh_cn # 中文界面

3. 接口注解写法（OpenAPI3标准）

Java 复制代码

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/user")
@Tag(name = "用户管理模块", description = "用户CRUD接口")
public class UserController {

    @Operation(summary = "根据ID查询用户")
    @GetMapping("/{id}")
    public String getUser(
            @Parameter(name = "id", description = "用户ID", required = true)
            @PathVariable Long id) {
        return "用户ID：" + id;
    }

    @Operation(summary = "新增用户")
    @PostMapping("/add")
    public String addUser(@RequestBody UserDTO userDTO) {
        return "新增成功：" + userDTO;
    }
}

四、启动访问

启动项目，打开浏览器：

Plain 复制代码

http://localhost:8080/doc.html

即可看到中文、可调试、可导出的接口文档页面。

五、常用注解速查

注解	作用	实际用法（代码示例）
@Tag	模块/分组说明（加在Controller上）	// 标注整个用户管理Controller的功能，方便文档分组查看@Tag(name = "用户管理模块", description = "负责用户注册、查询、修改、删除等接口，支持分页、条件查询") ``@RestController ``@RequestMapping("/user") ``public class UserController {}
@Operation	接口说明（加在方法上）	// 描述单个接口的功能、请求方式，补充备注说明@Operation(summary = "根据ID查询用户详情", description = "传入用户唯一ID，返回用户完整信息（含角色、权限），ID不可为空", notes = "若ID不存在，返回404提示") ``@GetMapping("/{id}") ``public Result getUserById(@PathVariable Long id) {}
@Parameter	参数说明（路径、查询、Header参数）	// 单独标注单个参数，明确是否必填、格式要求@GetMapping("/list") ``public Result getUserList( `` @Parameter(name = "pageNum", description = "页码，默认1", required = false, example = "1") `` @RequestParam(required = false, defaultValue = "1") Integer pageNum, `` @Parameter(name = "pageSize", description = "每页条数，默认10", required = false, example = "10") `` @RequestParam(required = false, defaultValue = "10") Integer pageSize) {}
@Parameters	多个参数组合	// 多个参数一起标注，简化代码，适用于参数较多的接口@GetMapping("/search") ``@Parameters({ `` @Parameter(name = "username", description = "用户名（模糊查询）", required = false), `` @Parameter(name = "status", description = "用户状态（0-禁用，1-正常）", required = false, example = "1") ``}) ``public Result searchUser(@RequestParam(required = false) String username, @RequestParam(required = false) Integer status) {}
@Schema	实体类字段说明	// 标注实体类字段，用于请求体、响应体的参数说明，文档中会显示字段详情@Data ``public class UserDTO { `` @Schema(name = "id", description = "用户ID（新增时无需传入，修改时必传）", example = "1001") `` private Long id; `` `` @Schema(name = "username", description = "用户名，长度2-16位，不可重复", required = true, example = "zhangsan") `` private String username; `` `` @Schema(name = "age", description = "用户年龄，18-60岁", required = false, example = "25") `` private Integer age; ``}