SpringDoc OpenAPI 全局配置实现所有字段默认必填的深度解析

在实际开发中，我们经常需要确保API文档中所有字段默认标记为必填(REQUIRED)，而不是采用框架默认的自动判断逻辑。本文将深入探讨如何在SpringDoc OpenAPI项目中实现这一需求，并分析其中的技术细节。

需求背景

在RESTful API设计中，明确字段是否必填对于接口消费者至关重要。SpringDoc默认会根据Java类的字段定义自动判断必填属性，但某些场景下我们需要：

1. 强制所有字段默认必填
2. 仍允许通过注解覆盖默认行为
3. 保持与现有代码的兼容性

核心解决方案

通过自定义ModelResolver可以完美实现这一需求。以下是实现的关键代码：

@Configuration
public class RequiredFieldsModelResolver extends ModelResolver {
    
    public RequiredFieldsModelResolver(ObjectMapper mapper) {
        super(mapper);
    }

    @Override
    protected Schema.RequiredMode resolveRequiredMode(Schema schema) {
        if (schema == null || schema.requiredMode() == null 
            || schema.requiredMode() == Schema.RequiredMode.AUTO) {
            return Schema.RequiredMode.REQUIRED;
        }
        return schema.requiredMode();
    }
}

这段代码的工作原理是：

1. 继承SpringDoc默认的模型解析器
2. 重写resolveRequiredMode方法
3. 当字段的requiredMode为null或AUTO时，强制返回REQUIRED
4. 保留显式设置的NOT_REQUIRED等模式

实现细节分析

字段必填的优先级

1. 显式注解（最高优先级）
2. 自定义解析器逻辑
3. 框架默认行为（最低优先级）

与Swagger核心的交互

值得注意的是，Swagger核心库会对必填字段列表进行自动排序，这是出于以下考虑：

1. 确保生成的文档一致性
2. 便于文档比较
3. 符合OpenAPI规范的建议

实际效果验证

通过以下代码可以验证生成的Schema：

ResolvedSchema resolvedSchema = ModelConverters.getInstance(true)
        .resolveAsResolvedSchema(
                new AnnotatedType(YourClass.class).resolveAsRef(false));

最佳实践建议

1. 谨慎使用全局必填：不是所有场景都适合强制必填，特别是对已有系统改造时
2. 结合注解使用：对于确实非必填的字段，使用@Schema(requiredMode = NOT_REQUIRED)
3. 文档测试：生成文档后务必进行人工验证
4. 版本控制：这类改动建议伴随API版本升级

扩展思考

这种实现方式展示了SpringDoc的强大扩展性。类似地，我们还可以：

1. 基于业务规则动态设置必填属性
2. 根据环境配置切换必填策略
3. 实现更复杂的字段验证逻辑集成

通过理解这个案例，开发者可以更深入地掌握SpringDoc的定制化能力，打造更符合项目需求的API文档生成方案。