SpringDoc OpenAPI中@Hidden注解失效问题解析与解决方案

问题背景

在Spring Boot应用中使用SpringDoc OpenAPI生成API文档时，开发人员可能会遇到一个常见问题：当使用@Hidden注解标记REST控制器类时，该控制器仍然会出现在生成的OpenAPI文档中。这个问题在Spring Boot 3.2.4和springdoc-openapi-starter-common 2.6.0版本中尤为明显。

问题根源分析

这个问题的根本原因在于Spring框架的默认代理机制CGLIB。当Spring创建控制器类的代理时，会在原始类名后添加"$$SpringCGLIB$$0"后缀。SpringDoc OpenAPI在检查类是否被@Hidden注解标记时，直接使用了代理类名进行比较，导致无法正确识别原始类上的注解。

具体来说，问题出在AbstractOpenApiResource类的isHiddenRestControllers方法中，该方法直接使用isAssignableFrom方法比较类对象，而没有考虑Spring代理类的情况。

技术细节

Spring框架使用CGLIB或JDK动态代理来实现AOP功能。对于没有实现接口的类，Spring默认使用CGLIB代理，这会在原始类名后添加特殊后缀。这种代理机制虽然对业务逻辑透明，但在反射和注解处理时需要特别注意。

在SpringDoc OpenAPI的实现中，isHiddenRestControllers方法通过检查类是否被@Hidden注解标记来决定是否在文档中显示该控制器。由于代理类名的变化，这个检查逻辑失效了。

解决方案

Spring框架提供了ClassUtils.getUserClass方法来获取代理背后的原始类。我们可以利用这个方法来解决注解识别问题。具体实现方式是在检查@Hidden注解时，先通过getUserClass方法获取原始类，然后再进行比较。

这个解决方案已经被项目维护者采纳并合并到代码库中。修改后的逻辑能够正确处理代理类情况，确保@Hidden注解按预期工作。

最佳实践

1. 当遇到Spring代理导致的注解识别问题时，优先考虑使用Spring提供的工具类如ClassUtils来处理
2. 在自定义注解处理器时，始终考虑代理类的情况
3. 对于重要的API文档控制，除了类级别的@Hidden注解，也可以考虑使用方法级别的控制

总结

Spring框架的代理机制虽然强大，但在处理注解时可能会带来一些意外情况。理解这些机制并学会使用Spring提供的工具类来处理代理类问题，是每个Spring开发者应该掌握的技能。通过这次问题的分析和解决，我们不仅解决了@Hidden注解失效的问题，也加深了对Spring代理机制的理解。

对于使用SpringDoc OpenAPI的开发者来说，升级到包含此修复的版本后，可以放心使用@Hidden注解来控制API文档的生成，确保文档的准确性和完整性。