如何在SpringDoc生成的OpenAPI文件中添加额外枚举？

你遇到的问题是因为ModelConverters处理枚举类型时，返回的schema属性是指向自身的引用，而非实际的枚举定义。可以通过以下两种方式修复：

方式一：从ResolvedSchema中提取实际枚举定义 #

在添加模型到Components时，判断如果是枚举且当前schema为自引用，就从ResolvedSchema的schemas集合里取出实际的枚举定义：

@Bean
public OpenAPI customOpenAPI() {
    Components components = new Components();
    ModelConverters modelConverters = ModelConverters.getInstance();
    
    getModelsNotUsedInControllersToGenerate()
        .forEach(model -> {
            ResolvedSchema resolvedSchema = modelConverters.readAllAsResolvedSchema(model);
            Schema<?> targetSchema = resolvedSchema.schema;
            
            // 处理枚举的自引用问题
            if (model.isEnum() && targetSchema instanceof RefSchema refSchema) {
                String schemaName = refSchema.get$ref().split("/")[3];
                targetSchema = resolvedSchema.schemas.get(schemaName);
            }
            
            components.addSchemas(model.getSimpleName(), targetSchema);
        });
    
    return new OpenAPI()
        .components(components)
        .info(new Info().title("API"));
}

方式二：手动构建枚举Schema #

如果方式一不生效，也可以直接手动构建枚举的Schema对象，指定枚举的所有取值：

@Bean
public OpenAPI customOpenAPI() {
    Components components = new Components();
    ModelConverters modelConverters = ModelConverters.getInstance();
    
    getModelsNotUsedInControllersToGenerate()
        .forEach(model -> {
            if (model.isEnum()) {
                StringSchema enumSchema = new StringSchema();
                // 获取枚举常量并转为字符串列表
                List<String> enumValues = Arrays.stream(model.getEnumConstants())
                    .map(Object::toString)
                    .collect(Collectors.toList());
                enumSchema.setEnum(enumValues);
                components.addSchemas(model.getSimpleName(), enumSchema);
            } else {
                components.addSchemas(
                    model.getSimpleName(),
                    modelConverters.readAllAsResolvedSchema(model).schema);
            }
        });
    
    return new OpenAPI()
        .components(components)
        .info(new Info().title("API"));
}

这两种方式都能避免枚举出现自引用，生成符合预期的OpenAPI枚举Schema定义。

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