Quarkus smallrye-openapi添加@Schema描述后allOf异常生成问题求助

问题原因 #

当在自定义对象/枚举类型的字段上添加@Schema(description = "...")注解时，SmallRye OpenAPI为了同时保留字段描述和引用定义，会生成包含allOf的结构，这会导致Swagger UI无法正常解析引用类型。

解决方案 #

方案1：将描述移至目标类型本身 #

把描述添加到枚举或自定义对象的类级别@Schema注解中，而非字段上：

@Schema(description = "Enum of the file ingestion options.")
public enum EIngestionType {
    // 枚举值
    UPLOAD, IMPORT
}

字段上无需添加额外的@Schema注解（或仅保留@Schema(implementation = EIngestionType.class)），此时生成的OpenAPI规范会直接引用组件：

ingestionType:
  $ref: '#/components/schemas/EIngestionType'

描述会自动出现在组件定义的EIngestionType中，既保留了说明，又避免了allOf结构。

方案2：通过配置禁用描述与引用的合并 #

在application.properties中添加以下配置，强制SmallRye OpenAPI不生成allOf结构，直接将字段描述与引用合并：

quarkus.smallrye-openapi.merge-descriptions-with-refs=false

添加该配置后，即使在字段上添加@Schema(description = "...")，生成的规范也会是：

ingestionType:
  description: Enum of the file ingestion options.
  $ref: '#/components/schemas/EIngestionType'

这种格式符合OpenAPI规范，Swagger UI可以正常解析。

方案3：使用@Schema的ref属性明确指定 #

如果需要在字段上保留描述，也可以通过@Schema的ref属性直接指定引用，同时添加描述：

@Schema(ref = "#/components/schemas/EIngestionType", description = "Enum of the file ingestion options.")
private EIngestionType ingestionType;

配合方案2的配置，即可避免生成allOf结构。

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