升级OpenAPI至3.1.0后Swagger UI整数默认值异常，如何全局设为0

由于OpenAPI 3.1.0采用JSON Schema 2020-12规范，Swagger UI对未指定示例/默认值的整数类型，默认会生成JSON最大安全整数（9007199254740991），而非3.0.x版本的0。以下是无需降级、全局设置整数默认示例为0的解决方案：

方法一：自定义Schema处理器（springdoc-openapi环境） #

如果使用springdoc-openapi作为OpenAPI生成工具，可通过实现SchemaCustomizer全局修改整数Schema的默认值和示例：

import org.springdoc.core.customizers.SchemaCustomizer;
import org.springframework.stereotype.Component;
import io.swagger.v3.oas.models.media.Schema;

@Component
public class IntegerDefaultSchemaCustomizer implements SchemaCustomizer {

    // 处理方法参数中的Schema
    @Override
    public void customize(Schema schema, org.springframework.core.MethodParameter methodParameter) {
        setIntegerDefaults(schema);
    }

    // 处理实体类中的Schema
    @Override
    public void customize(Schema schema, Class<?> clazz) {
        setIntegerDefaults(schema);
    }

    private void setIntegerDefaults(Schema schema) {
        if ("integer".equals(schema.getType())) {
            // 仅当未手动设置时覆盖
            if (schema.getDefault() == null) {
                schema.setDefault(0);
            }
            if (schema.getExample() == null) {
                schema.setExample(0);
            }
        }
    }
}

该类会被Spring自动扫描加载，对所有生成的整数类型Schema生效，且不会覆盖已手动设置的default或example值。

方法二：自定义Model转换器（通用Swagger Core环境） #

如果直接使用swagger-core库，可通过注册自定义ModelConverter来修改Schema生成逻辑：

1. 实现ModelConverter #

import io.swagger.v3.core.converter.ModelConverter;
import io.swagger.v3.core.converter.ModelConverterContext;
import io.swagger.v3.oas.models.media.Schema;
import java.lang.reflect.Type;
import java.util.Iterator;

public class IntegerDefaultValueConverter implements ModelConverter {

    @Override
    public Schema resolve(Type type, ModelConverterContext context, Iterator<ModelConverter> chain) {
        Schema schema = chain.next().resolve(type, context, chain);
        if (schema != null && "integer".equals(schema.getType())) {
            if (schema.getDefault() == null) {
                schema.setDefault(0);
            }
            if (schema.getExample() == null) {
                schema.setExample(0);
            }
        }
        return schema;
    }
}

2. 在OpenAPI配置中注册转换器 #

import io.swagger.v3.core.converter.ModelConverters;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.Info;
import io.swagger.v3.oas.models.License;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customizeOpenAPI() {
        // 注册自定义转换器
        ModelConverters.getInstance().addConverter(new IntegerDefaultValueConverter());
        
        final String securitySchemeName = "bearerAuth";
        return new OpenAPI()
            .addSecurityItem(new SecurityRequirement().addList(securitySchemeName))
            .components(new Components().addSecuritySchemes(securitySchemeName,
                new SecurityScheme()
                    .name(securitySchemeName)
                    .type(SecurityScheme.Type.HTTP)
                    .scheme("bearer")
                    .bearerFormat("JWT")))
            .info(new Info().title("Project example API")
                .summary("Api Documentation")
                .version("3.1.0")
                .license(new License().name("Apache 2.0").identifier("Apache-2.0")
                    .url("https://www.apache.org/licenses/LICENSE-2.0.html")))
            .openapi("3.1.0");
    }
}

注意事项 #

• 上述方案仅对未通过@Schema(defaultValue = "xxx")或代码手动设置默认值/示例的整数字段生效
• 确保使用的swagger-core或springdoc-openapi版本与OpenAPI 3.1.x兼容，建议使用最新稳定版
• 如果是SpringFox环境，思路类似，但需使用SpringFox对应的扩展接口修改Schema生成逻辑

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