Knife4j中多层级泛型字段注释不显示的解决方案

在使用Knife4j与Spring Boot 3和Spring Doc集成时，开发者可能会遇到一个常见问题：当API返回对象包含多层级泛型结构时，Swagger UI中无法正确显示字段的注释信息。这个问题主要源于Spring Doc对泛型类处理的特殊机制。

问题现象

当API返回类似Result<Page<Entity>>这样的嵌套泛型结构时，虽然实体类上已经添加了@Schema注解，但在生成的API文档中，内部实体类的字段描述却无法正常显示。开发者只能看到字段名称，而看不到对应的注释信息。

根本原因

经过分析，这个问题主要由两个因素导致：

1. Lombok与Schema注解的冲突：当泛型类使用了Lombok的@Data注解时，Spring Doc可能无法正确解析类上的@Schema注解。

2. 泛型类与Schema注解的不兼容：@Schema注解设计上代表唯一的Schema定义，这与泛型类的多态特性存在本质冲突。Spring Doc在处理泛型类时，会忽略类级别的@Schema注解。

解决方案

方案一：避免在泛型类上使用Lombok注解

对于需要显示字段注释的泛型类，建议移除Lombok的@Data注解，改为显式定义getter/setter方法。这样可以确保Spring Doc能够正确解析类上的Schema注解。

// 不推荐
@Data
@Schema(description = "分页响应对象")
public class PageResult<T> {
    private List<T> records;
    private long total;
}

// 推荐
@Schema(description = "分页响应对象")
public class PageResult<T> {
    private List<T> records;
    private long total;
    
    // 显式定义getter/setter
    public List<T> getRecords() {
        return records;
    }
    
    public void setRecords(List<T> records) {
        this.records = records;
    }
    
    // 其他getter/setter
}

方案二：自定义注解扩展

对于复杂场景，可以通过实现Spring Doc的插件体系来自定义解析规则：

1. 创建自定义注解替代@Schema
2. 实现OpenApiCustomiser接口
3. 在自定义逻辑中处理泛型类的注释信息

这种方式虽然灵活，但实现成本较高，适合有特殊需求的场景。

最佳实践建议

1. 对于简单的DTO对象，可以直接使用@Schema注解
2. 对于包含泛型的包装类，建议避免使用Lombok注解
3. 保持API返回类型的层级尽可能简单，避免过深的嵌套结构
4. 对于必须使用复杂泛型结构的场景，考虑使用方案二进行扩展

通过以上方法，开发者可以解决Knife4j与Spring Doc集成时泛型类字段注释不显示的问题，生成更加完善的API文档。