SpringDoc OpenAPI 深度解析：如何实现全局非空校验策略

在基于Spring Boot的Java应用开发中，保持严格的非空策略是保证系统健壮性的重要实践。许多团队选择全面采用Java的Optional类型来明确表达值的可选性，但这种设计理念在与OpenAPI规范集成时往往会遇到挑战。

核心问题分析

传统SpringDoc的默认行为是将所有DTO属性视为可选（nullable），这与许多团队的实际业务约束存在矛盾。开发者不得不为每个非空字段添加@NotNull注解，导致以下问题：

1. 注解污染：API层充斥着大量重复性注解
2. 维护风险：容易遗漏注解导致规范与实际约束不一致
3. 规范偏差：业务模型中的非空约束无法自动映射到API文档

技术解决方案

通过扩展Swagger Core的ModelResolver组件，我们可以重写字段必需性判定逻辑：

public class StrictModelResolver extends ModelResolver {
    @Override
    protected RequiredMode resolveRequiredMode(Schema schema) {
        if (schema != null && schema.requiredMode() != RequiredMode.AUTO) {
            return schema.requiredMode();
        }
        return RequiredMode.REQUIRED; // 默认设为必需
    }
}

该实现将全局默认值设为REQUIRED，同时保留通过@Schema注解显式声明的灵活性。对于Optional类型的特殊处理，由于Swagger Core架构限制，需要更深入的改造：

1. 类型识别：在模型解析阶段捕获字段的JavaType
2. 动态调整：当类型为Optional时自动标记为NOT_REQUIRED
3. 注解协同：确保与现有注解逻辑无冲突

最佳实践建议

1. 分层策略：在领域层使用Optional，在DTO层结合@Schema配置
2. 文档验证：通过自动化测试确保OpenAPI规范与实际约束一致
3. 渐进迁移：对于已有项目，可以先启用全局REQUIRED再逐步优化

架构思考

这种配置化方案体现了契约优先（Contract-First）的设计理念，使API规范能够真实反映业务约束。相比GraphQL的方案选择，OpenAPI的优势在于：

• 与现有Java生态更深度集成
• 支持更丰富的文档描述能力
• 保持RESTful架构的可见性

通过合理的扩展和配置，SpringDoc OpenAPI完全可以满足严格类型系统的文档化需求，避免因技术限制而进行架构妥协。