SpringBoot集成Knife4j实现接口文档和参数校验_Java

一、核心认知

1.1 什么是springdoc openapi？

springdoc openapi 是 spring boot 生态中替代传统 swagger2 的接口文档工具，基于 openapi 3.0 规范，支持 spring boot 3.x（也兼容 2.x），核心优势是配置简单、原生支持 spring web/spring webflux。

补充说明：

swagger2 已停止维护，springdoc 是目前官方推荐的替代方案
openapi 3.0 是国际通用接口描述标准，前后端分离开发必备
spring boot 3.x 使用 jakarta 包名，必须使用对应兼容版本

1.2 什么是 knife4j？

knife4j 是国人开发的接口文档增强工具，底层基于 openapi 规范（兼容 swagger/springdoc），但提供了比原生 swagger ui 更美观、更贴合国内开发者习惯的中文界面，还增加了离线文档导出、接口调试、权限控制等实用功能！

原生 springdoc 与 knife4j 对比

特性	原生 springdoc (swagger ui)	knife4j (该依赖)
界面语言	英文	中文 (可切换)
界面风格	简约但不够友好	更美观、贴合国内使用习惯
额外功能	基础接口调试	离线文档导出 (pdf/html)、接口排序、权限控制、全局参数配置
底层规范	openapi 3.0	完全兼容 openapi 3.0 (复用 springdoc 注解)
适配版本	spring boot 2.x/3.x	该版本适配 spring boot3.x (jakarta)

1.3 数据校验核心

jakarta validation + hibernate validator

jakarta.validation-api：提供数据校验的标准 api（包含@valid、@notblank等核心注解），定义校验规范。
hibernate-validator：是上述规范的主流实现框架，负责实际的校验逻辑执行，是 springboot 中数据校验的必备依赖。

二、快速使用

2.1 引入依赖

    <dependencies>
        <!-- spring web 核心依赖 -->
        <dependency>
            <groupid>org.springframework.boot</groupid>
            <artifactid>spring-boot-starter-web</artifactid>
        </dependency>
        <!-- 测试依赖 -->
        <dependency>
            <groupid>org.springframework.boot</groupid>
            <artifactid>spring-boot-starter-test</artifactid>
            <scope>test</scope>
        </dependency>
        <!-- knife4j openapi3 适配springboot3.x(jakarta) -->
        <dependency>
            <groupid>com.github.xiaoymin</groupid>
            <artifactid>knife4j-openapi3-jakarta-spring-boot-starter</artifactid>
            <version>4.3.0</version>
        </dependency>
        <!-- lombok 简化实体代码 -->
        <dependency>
            <groupid>org.projectlombok</groupid>
            <artifactid>lombok</artifactid>
            <optional>true</optional>
        </dependency>
    </dependencies>

2.2 修改配置文件

# 服务器端口（可选，默认8080）
server:
  port: 8080
# springdoc 核心配置
springdoc:
  info:
    title: "用户管理系统api" # 接口文档标题
    version: "v1.0.0" # 接口文档版本
    description: "基于springdoc+knife4j的接口文档示例，集成数据校验功能" # 接口文档描述
# knife4j 增强配置
knife4j:
  enable: true # 开启knife4j所有增强功能（核心）
  setting:
    language: zh_cn # 界面默认语言：中文
    enable-footer: false # 关闭底部版权信息（可选，美化界面）
    enable-request-cache: false # 关闭请求缓存（可选）

2.3 编写实体类

import io.swagger.v3.oas.annotations.media.schema;
import jakarta.validation.constraints.notblank;
import jakarta.validation.constraints.notnull;
import jakarta.validation.constraints.min;
import jakarta.validation.constraints.max;
import lombok.allargsconstructor;
import lombok.data;
import lombok.noargsconstructor;
/**
 * 用户信息实体
 */
@schema(name = "user", description = "用户信息实体，包含用户名、年龄核心字段")
@data // 生成get/set/tostring等方法
@allargsconstructor // 全参构造
@noargsconstructor // 无参构造
public class user {
    @schema(description = "用户名", required = true, example = "张三")
    @notblank(message = "用户名不能为空") // 非空校验：字符串不能为null、空字符串、纯空格
    private string name;
    @schema(description = "用户年龄", required = false, example = "25", minimum = "1", maximum = "120")
    @notnull(message = "年龄不能为null") // 非null校验
    @min(value = 1, message = "年龄不能小于1岁") // 最小值校验
    @max(value = 120, message = "年龄不能大于120岁") // 最大值校验
    private integer age;
}

2.4 编写 controller 层

import io.swagger.v3.oas.annotations.operation;
import io.swagger.v3.oas.annotations.parameter;
import io.swagger.v3.oas.annotations.parameters;
import io.swagger.v3.oas.annotations.enums.parameterin;
import io.swagger.v3.oas.annotations.media.content;
import io.swagger.v3.oas.annotations.media.schema;
import io.swagger.v3.oas.annotations.responses.apiresponse;
import io.swagger.v3.oas.annotations.tags.tag;
import jakarta.validation.valid;
import com.ruangong.springbootdemo2.pojo.user;
import org.springframework.web.bind.annotation.*;

// 1. @tag:controller 级别的接口分类
@tag(name = "用户管理接口", description = "用户新增、查询、修改、删除操作")
@restcontroller
@requestmapping("/user")
public class usercontroller {

    // 2. @operation:方法级别的接口描述
    @operation(
        summary = "新增用户", // 接口简短描述
        description = "传入用户信息，新增一条用户记录（用户名不能为空）", // 详细描述
        // 3. @apiresponse:定义接口响应结果
        responses = {
            @apiresponse(responsecode = "200", description = "新增成功",
                content = @content(schema = @schema(implementation = string.class))),
            @apiresponse(responsecode = "400", description = "参数校验失败")
        }
    )
    @postmapping
    public string adduser(@valid @requestbody user user) {
        return "新增用户成功:" + user.getname();
    }

    // 4. @parameters/@parameter:描述路径/请求参数
    @operation(summary = "根据id查询用户")
    @parameters({
        @parameter(name = "id", description = "用户id", required = true, in = parameterin.path, example = "1001")
    })
    @getmapping("/{id}")
    public user getuserbyid(@pathvariable long id) {
        user user = new user();
        user.setname("张三");
        user.setage(25);
        return user;
    }
}

2.5 启动项目并访问接口文档

启动成功后，访问以下地址：

knife4j 专属中文界面（推荐）：http://localhost:8080/doc.html
兼容原生 swagger ui：http://localhost:8080/swagger-ui.html
openapi 原始数据：http://localhost:8080/v3/api-docs

补充说明：

doc.html 是 knife4j 增强界面，支持中文、调试、导出、全局参数
swagger-ui.html 保留兼容，方便老项目迁移
v3/api-docs 是标准 openapi 格式，可导入 postman/yapi

三、核心注解说明

3.1 接口文档注解（openapi3/springdoc）

注解	作用级别	核心作用
@tag	controller	接口模块分类，定义模块名称和描述
@operation	方法	描述单个接口的名称、详细说明
@apiresponse	方法	定义接口的响应码、响应描述、响应数据类型
@parameters/@parameter	方法	描述路径参数 / 请求参数的名称、是否必传、示例值
@schema	实体 / 实体字段	描述实体 / 字段的含义、是否必传、示例值、范围

3.2 数据校验注解（jakarta validation）

注解	作用级别	核心作用
@valid	方法参数	触发参数校验，绑定实体的校验规则
@notblank	字符串字段	非空校验（禁止 null、空字符串、纯空格）
@notnull	任意字段	非 null 校验（允许空字符串）
@notempty	集合 / 数组	集合 / 数组不能为空
@size	字符串 / 集合	字符串 / 集合长度范围校验
@min/@max	数值字段	数值范围校验
@email	字符串字段	邮箱格式校验

注意事项

springboot 版本适配：springboot3.x 需使用knife4j-openapi3-jakarta-spring-boot-starter，springboot2.x 使用非 jakarta 版本的 knife4j 依赖。
校验注解的使用场景：@notblank仅适用于字符串，数值类型使用@notnull+@min/@max组合。
@valid 注解的位置：需加在请求体参数前（@requestbody后），否则无法触发校验。
knife4j 依赖的特性：knife4j 已内置 springdoc，无需单独引入 springdoc 的依赖，避免版本冲突。
jdk 版本要求：springboot3.x 最低要求 jdk17，需保证开发环境 jdk 版本符合要求。

以上就是springboot集成knife4j实现接口文档和参数校验的详细内容，更多关于springboot knife4j接口文档和参数校验的资料请关注代码网其它相关文章！