Quarkus中OpenAPI配置疑问：隐藏类与字段描述设置

使用SmallRye OpenAPI提供的@Schema(hidden = true)注解即可实现需求：

• 如果是对象组合中引用的属性需要隐藏，直接在该属性上添加注解；
• 如果要隐藏整个类（比如自定义的Era、CalendarDate），在类定义上标注注解。

代码示例：

import io.smallrye.openapi.api.annotations.Schema;
import java.util.Date;

// 请求/响应实体类
public class OrderDTO {
    private String orderNo;
    
    // 隐藏JDK自带的Date类型属性
    @Schema(hidden = true)
    private Date submitTime;
    
    // 隐藏自定义的CalendarDate类型属性
    @Schema(hidden = true)
    private CalendarDate validDate;
    
    // getter/setter 省略
}

// 隐藏整个自定义Era类
@Schema(hidden = true)
public class Era {
    private String code;
    // getter/setter 省略
}

@Parameter注解仅针对路径参数、查询参数等场景生效，请求体内的字段描述需要用@Schema(description = "你的描述内容")注解标记在实体类的对应字段上。

代码示例：

import io.smallrye.openapi.api.annotations.Schema;

// 请求体实体类
public class CustomerAccountDTO {
    // 为该字段添加描述，会在OpenAPI Schema中显示
    @Schema(description = "客户账户的唯一标识，由16位数字组成")
    private String accountNumberCustomerAccount;
    
    private String customerName;
    
    // getter/setter 省略
}

// 接口类
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.core.MediaType;

@Path("/customer/accounts")
public class AccountResource {
    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    public void createCustomerAccount(CustomerAccountDTO request) {
        // 业务逻辑实现
    }
}

内容的提问来源于stack exchange，提问作者Cesar Justo