Java应用使用atlassian.oai.validator拆分同类OpenAPI校验错误

atlassian.oai.validator 没有提供内置配置项直接关闭必填字段缺失错误的合并行为，要实现单字段对应单条错误提示的需求，可通过以下两种方式实现，其中后置拆分方案侵入性最低，推荐优先使用。

不需要修改校验器核心逻辑，仅在拿到校验结果后对合并的错误做解析拆分即可，实现成本最低，兼容性最好：

• 识别合并的必填项缺失错误：这类错误消息固定格式为Object has missing required properties (["字段1","字段2"])
• 通过正则提取所有缺失的字段名，为每个字段生成独立的错误消息
• 保留原错误的级别、请求路径、上下文等附加信息，替换原合并错误条目

实现代码参考：

import com.atlassian.oai.validator.report.ValidationReport;
import java.util.ArrayList;
import java.util.List;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class ValidationReportSplitter {
    // 匹配合并的必填项缺失错误，提取括号内的字段列表
    private static final Pattern MISSING_REQUIRED_PATTERN = 
        Pattern.compile("^Object has missing required properties \\(\\[(.*)]\\)$");

    public static ValidationReport splitMergedRequiredErrors(ValidationReport originalReport) {
        List<ValidationReport.Message> processedMessages = new ArrayList<>();
        
        for (ValidationReport.Message msg : originalReport.getMessages()) {
            String msgContent = msg.getMessage();
            Matcher matcher = MISSING_REQUIRED_PATTERN.matcher(msgContent);
            
            if (matcher.matches()) {
                String[] missingFields = matcher.group(1).split(",");
                for (String field : missingFields) {
                    // 清理字段名前后的引号、空格
                    String cleanField = field.trim().replace("\"", "");
                    // 保留原错误的所有上下文信息，仅替换消息内容
                    ValidationReport.Message singleMsg = ValidationReport.Message.create(
                        msg.getKey(),
                        String.format("Object has missing required property \"%s\"", cleanField)
                    ).withLevel(msg.getLevel())
                     .withAdditionalInfo(msg.getAdditionalInfo())
                     .withNestedMessages(msg.getNestedMessages())
                     .build();
                    processedMessages.add(singleMsg);
                }
            } else {
                // 非合并类错误直接保留
                processedMessages.add(msg);
            }
        }
        return ValidationReport.from(processedMessages);
    }
}

使用时，只需要在调用校验器获取原始ValidationReport后，传入该工具方法处理，即可得到符合预期的拆分结果，输出格式和给出的期望示例完全一致。

如果需要从错误生成源头就避免合并，可以替换组件默认的required关键字处理器：

• 自定义JsonSchemaValidator实现，重写必填字段校验的错误生成逻辑，每检测到一个缺失字段就生成一条独立错误
• 在初始化OpenApiValidator时，通过Builder的withJsonSchemaValidatorFactory方法传入自定义的校验器工厂，替换默认实现
• 该方案需要适配当前引入的validator版本，不同版本的Schema校验内部类路径、接口定义可能存在差异，后续升级版本需要同步调整自定义逻辑，维护成本较高。

提示：如果项目中配置了错误消息国际化模板，拆分单条错误时要注意和现有国际化文案格式保持统一。

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