如何修改SpringDoc生成OpenAPI规范的默认行为，实现字段默认必填（仅添加@Nullable时设为可选）

当然可以！SpringDoc提供了非常灵活的扩展点来调整它的默认行为，刚好能适配你“默认必填、仅@Nullable标记可选”的开发习惯。下面是两种可行的实现方案：

方案一：自定义Schema处理器（推荐） #

你可以通过实现ModelConverterPlugin接口，拦截SpringDoc生成Schema的过程，手动修改字段的必填规则：

import io.swagger.v3.core.converter.ModelConverterContext;
import io.swagger.v3.core.converter.ModelConverterPlugin;
import io.swagger.v3.core.converter.ResolvedSchema;
import io.swagger.v3.oas.models.media.Schema;
import org.springframework.stereotype.Component;
import org.springframework.lang.Nullable;

import java.lang.reflect.Field;
import java.lang.reflect.Type;
import java.util.ArrayList;
import java.util.Iterator;

@Component
public class DefaultRequiredSchemaPlugin implements ModelConverterPlugin {

    @Override
    public boolean supports(ModelConverterContext context, Type type) {
        // 只处理实体类类型，排除基础类型和集合
        return type instanceof Class<?> && !((Class<?>) type).isPrimitive();
    }

    @Override
    public ResolvedSchema resolve(Type type, ModelConverterContext context, Iterator<ModelConverterPlugin> chain) {
        // 先让默认处理器生成基础Schema
        ResolvedSchema resolvedSchema = chain.next().resolve(type, context, chain);
        Schema<?> schema = resolvedSchema.schema;
        
        if (schema != null && schema.getProperties() != null) {
            schema.getProperties().forEach((propName, propSchema) -> {
                boolean isNullable = false;
                // 检查字段是否带有@Nullable注解
                if (type instanceof Class<?>) {
                    try {
                        Field field = ((Class<?>) type).getDeclaredField(propName);
                        isNullable = field.isAnnotationPresent(Nullable.class);
                        // 如果字段在父类，这里可以扩展遍历父类字段的逻辑
                    } catch (NoSuchFieldException e) {
                        // 忽略字段不存在的情况（比如getter生成的属性）
                    }
                }
                
                // 没有@Nullable注解则设为必填
                if (!isNullable) {
                    propSchema.setRequired(true);
                    // 将字段加入Schema的必填列表
                    if (schema.getRequired() == null) {
                        schema.setRequired(new ArrayList<>());
                    }
                    if (!schema.getRequired().contains(propName)) {
                        schema.getRequired().add(propName);
                    }
                }
            });
        }
        
        return resolvedSchema;
    }
}

这个组件会被Spring自动扫描并加载到SpringDoc的处理流程中：

• 它会遍历每个实体类的所有字段，检查是否带有@Nullable（不管是Spring的还是Javax的注解，只要类路径对应就行）
• 没有该注解的字段，会被强制设置为必填，同时加入到OpenAPI Schema的必填字段列表里

方案二：全局配置调整（简化版） #

如果你不想写复杂的插件，也可以通过自定义ModelConverter并注册到SpringDoc的配置中，核心逻辑和方案一一致：

import org.springdoc.core.SpringDocConfigProperties;
import org.springdoc.core.SpringDocConfiguration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SpringDocCustomConfig {

    @Bean
    public SpringDocConfiguration springDocConfiguration(SpringDocConfigProperties properties) {
        SpringDocConfiguration config = new SpringDocConfiguration(properties);
        // 注册自定义的Schema转换器
        config.getModelConverters().addConverter(new DefaultRequiredSchemaConverter());
        return config;
    }
    
    // 这里的DefaultRequiredSchemaConverter实现逻辑和方案一的插件类似，
    // 只是需要实现io.swagger.v3.core.converter.ModelConverter接口
}

注意事项 #

• 如果你的字段上显式标注了@Schema(required = true/false)，这个手动配置的优先级会高于我们的默认规则，不用担心被覆盖
• 对于父类继承来的字段，方案一的代码可以扩展为遍历父类的字段，确保注解检查的完整性
• 确保你项目中已经引入了对应的@Nullable注解依赖（比如Spring的org.springframework.lang.Nullable）

这样调整后，SpringDoc生成的OpenAPI文档就会完全匹配你的开发习惯——所有字段默认必填，只有标记了@Nullable的字段才会被设为可选！

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