Swagger v2转OpenAPI v3：如何移除Header Schema默认生成的type字段

核心问题 #

使用Swagger/OpenAPI注解配置请求头时，框架会根据Java参数类型自动生成type字段（比如String类型参数会生成"type":"string"），但API门户要求请求头Schema不含type字段，否则判定为破坏性变更。

解决方案 #

根据项目环境，选择以下对应方法：

1. 单个请求头快速处理：通过@Schema注解覆盖type

在请求头参数的@Schema注解中，将type设为空字符串，同时按需指定nullable或example：

@RequestHeader(value = "X-Your-Header")
@Schema(type = "", nullable = true)
String yourHeader;

生成的Schema会仅保留"nullable":true，不会出现type字段。若只需保留example：

@RequestHeader(value = "X-Your-Header")
@Schema(type = "", example = "null")
String yourHeader;

2. SpringDoc环境全局批量处理：自定义SchemaCustomizer

如果项目基于Spring Boot使用SpringDoc（主流OpenAPI v3实现），可以自定义组件全局移除所有请求头参数的type字段：

@Component
public class HeaderSchemaTypeCleaner implements SchemaCustomizer {
    @Override
    public void customize(Schema schema, SchemaCustomizerContext context) {
        // 仅处理请求头类型的参数
        if ("header".equals(context.getParamType())) {
            schema.setType(null);
        }
    }
}

项目启动后，所有请求头的Schema都会自动移除type字段。

3. 非Spring项目（Swagger-Core）：自定义ModelConverter

纯Java项目使用swagger-core时，通过自定义ModelConverter清除请求头参数的type属性：

public class HeaderTypeRemoverConverter implements ModelConverter {
    @Override
    public Schema resolve(AnnotatedType type, ModelConverterContext context, Iterator<ModelConverter> chain) {
        Schema schema = chain.next().resolve(type, context, chain);
        
        // 判断当前参数是否为请求头参数
        if (type.getCtxAnnotations() != null) {
            for (Annotation ann : type.getCtxAnnotations()) {
                if (ann instanceof HeaderParam) {
                    schema.setType(null);
                    break;
                }
            }
        }
        return schema;
    }
}

然后将转换器注册到OpenAPI解析器：

ModelConverters.getInstance().addConverter(new HeaderTypeRemoverConverter());

OpenAPIV3Parser parser = new OpenAPIV3Parser();
OpenAPI openAPI = parser.read("your-api-spec.yaml", null, new ParserOptions());

注意事项 #

• 不要使用@Schema(implementation = Object.class)，这会生成"type":"object"，不符合需求。
• 生成OpenAPI文档后，务必确认type字段已移除再上传到API门户。

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