SpringDoc OpenAPI中ControllerAdvice与分组配置导致示例键重复问题解析

问题背景

在使用SpringDoc OpenAPI 2.8.1版本时，开发者发现当同时使用API分组功能和ControllerAdvice全局异常处理时，生成的OpenAPI规范文件会出现"example"键重复的问题，导致YAML文件无效。这个问题特别出现在访问特定API分组端点时，而访问完整API文档端点则表现正常。

问题现象

当项目配置满足以下条件时会出现问题：

1. 启用了API分组功能（springdoc.api-docs.groups.enabled=true）
2. 使用了@ControllerAdvice注解处理全局异常
3. 访问特定分组的OpenAPI端点（如/v3/api-docs.yaml/hello）

生成的YAML文件中会出现重复的"example"键，违反了YAML规范。例如在错误响应示例部分可能会看到类似以下无效内容：

example:
  code: 422
  message: ""
  functionalCode: ""
example:
  code: 500
  message: ""
  functionalCode: null

技术分析

这个问题源于SpringDoc OpenAPI 2.8.1版本在处理示例数据时的逻辑缺陷。当同时存在分组和全局异常处理时，示例生成逻辑在某些情况下会重复添加"example"键，而不是合并或替换。

关键因素包括：

1. 分组功能会为每个API组创建独立的OpenAPI模型
2. ControllerAdvice中的异常处理方法会为每个响应添加示例
3. 2.8.1版本在示例合并处理上存在缺陷

解决方案

该问题已在SpringDoc OpenAPI 2.8.3版本中得到修复。升级到最新版本是最推荐的解决方案，因为：

1. 新版本改进了示例生成逻辑，确保不会重复添加"example"键
2. 增加了对示例值为null时的处理，避免生成无效内容
3. 提供了更稳定的分组API支持

最佳实践建议

为避免类似问题，建议开发者：

1. 始终使用SpringDoc OpenAPI的最新稳定版本
2. 对于生产环境，定期检查并更新依赖版本
3. 在使用分组功能时，充分测试每个分组的OpenAPI输出
4. 考虑使用OpenAPI规范验证工具验证生成的文档

总结

SpringDoc OpenAPI是一个强大的工具，但在特定版本组合下可能会出现边缘情况。这个示例键重复问题展示了API文档生成过程中可能遇到的微妙问题。通过理解问题根源和保持依赖更新，开发者可以确保生成高质量、有效的OpenAPI规范文档。