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

    <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>

# 服务器端口（可选，默认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 # 关闭请求缓存（可选）

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;
}

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;
    }
}