本文介绍在 Spring Boot 3 + springdoc-openapi 环境下，无需拦截器或过滤器，即可通过 OpenApiCustomizer 为所有 API 请求自动添加预设的 test-header 自定义请求头，并支持 JSON 字符串默认值与结构化 Schema 两种配置方式。
本文介绍在 spring boot 3 + springdoc-openapi 环境下，无需拦截器或过滤器，即可通过 openapicustomizer 为所有 api 请求自动添加预设的 `test-header` 自定义请求头，并支持 json 字符串默认值与结构化 schema 两种配置方式。
在基于 springdoc-openapi 的 Swagger UI 集成中，若希望所有接口请求自动携带一个固定值的自定义请求头（例如 test-header: {"username":"swagger","email":"dummy@email"}），而不依赖前端手动填写或后端全局拦截，最佳实践是利用 OpenApiCustomizer 对 OpenAPI 文档进行声明式增强——它在文档生成阶段动态注入参数定义，使 Swagger UI 原生支持该 header 的默认填充与交互。
✅ 推荐方案：以字符串形式注入 JSON 默认值
这是最简洁、兼容性最强的方式。将 JSON 序列化为字符串作为 header 的默认值，Swagger UI 会自动将其显示在请求头输入框中，且服务端可直接解析：
@Bean
public OpenApiCustomizer getCustomizer() {
return openApi -> openApi.getPaths().values().stream()
.flatMap(pathItem -> pathItem.readOperations().stream())
.forEach(operation -> operation.addParametersItem(
new HeaderParameter()
.name("test-header")
.description("测试用身份信息（JSON 字符串格式）")
.required(false)
.schema(new Schema<>().type("string")
._default("{\"username\":\"swagger\",\"email\":\"dummy@email\"}")
.example("{\"username\":\"test-user\",\"email\":\"test@example.com\"}")
)
));
}? 效果说明：Swagger UI 中每个接口的「Try it out」区域将自动显示 test-header 输入框，默认值为 {"username":"swagger","email":"dummy@email"}，用户可编辑，也可直接发送。
⚠️ 注意事项与最佳实践
不要使用 ObjectSchema + explode=true 模拟 JSON 对象
原答案中第一种写法（ObjectSchema + explode(true)）会导致 OpenAPI 将其渲染为 username=swagger&email=dummy@email 的查询风格键值对，并非标准 JSON header，且无法被 @RequestHeader String testHeader 正确接收。该方式仅适用于 application/x-www-form-urlencoded 场景，不推荐用于 JSON header。-
服务端需自行反序列化
若 header 值为 JSON 字符串（如 {"username":"swagger","email":"dummy@email"}），控制器应使用 @RequestHeader String testHeader 接收，再通过 Jackson 或 Gson 解析为对象：@PostMapping("/person") public ResponseEntity<?> create(@RequestHeader("test-header") String testHeader) { try { JsonNode node = new ObjectMapper().readTree(testHeader); String username = node.path("username").asText(); String email = node.path("email").asText(); // ... 业务逻辑 } catch (JsonProcessingException e) { throw new IllegalArgumentException("Invalid test-header format", e); } return ResponseEntity.ok().build(); } 安全性提醒
此方式仅适用于开发/测试环境的便利性增强。生产环境中，敏感字段（如用户名、邮箱）不应通过客户端可控的 header 传递，而应通过认证令牌（如 JWT）或服务端会话管理。
✅ 总结
通过 OpenApiCustomizer 注入 header 是 springdoc-openapi 提供的官方扩展机制，零侵入、纯声明式、完全兼容 OpenAPI 3.0 规范。相比 Filter 或 HandlerInterceptor，它不改变运行时行为，只优化 API 文档体验，确保 Swagger UI 用户“开箱即用”。只需一个 Bean，即可统一管控所有端点的默认请求头，大幅提升测试效率与文档可用性。
