springdoc-openapi 2.7.0版本中SwaggerUiConfigParameters的变更解析

背景介绍

在Spring Boot应用中集成OpenAPI文档时，springdoc-openapi是一个非常流行的选择。它能够自动为Spring Boot应用生成OpenAPI 3.0规范的API文档，并提供Swagger UI界面。在2.7.0版本中，该项目对Swagger UI配置相关的类进行了一些重要调整。

核心变更点

在2.6.0版本中，SwaggerUiConfigParameters类是由springdoc-common模块自动配置的。但在2.7.0版本中，这一自动配置行为被移除了。这一变化主要出于以下考虑：

1. 对象引用隔离：为了确保每个请求都能获得独立的配置对象实例
2. 配置灵活性：给予开发者更大的控制权来管理Swagger UI的配置
3. 性能优化：减少不必要的bean创建和依赖注入

技术实现细节

在2.7.0版本中，SwaggerUiConfigParameters不再作为Spring Bean存在，而是改为在需要时即时创建。这种变化影响了自定义SwaggerIndexPageTransformer的实现方式。

旧版本实现方式

在2.6.0及之前版本中，开发者可以这样实现自定义转换器：

public class CustomTransformer extends AbstractSwaggerIndexTransformer {
    public CustomTransformer(SwaggerUiConfigParameters configParameters) {
        super(configParameters);
    }
    
    @Override
    public String transform(InputStream inputStream) throws IOException {
        return defaultTransformations(configParameters, inputStream);
    }
}

新版本推荐实现

在2.7.0版本中，推荐的做法是：

public class CustomTransformer extends AbstractSwaggerIndexTransformer {
    private final SwaggerUiConfigProperties swaggerUiConfig;
    
    public CustomTransformer(SwaggerUiConfigProperties swaggerUiConfig) {
        this.swaggerUiConfig = swaggerUiConfig;
    }
    
    @Override
    public String transform(InputStream inputStream) throws IOException {
        SwaggerUiConfigParameters configParameters = new SwaggerUiConfigParameters(swaggerUiConfig);
        return defaultTransformations(configParameters, inputStream);
    }
}

迁移建议

对于从2.6.0升级到2.7.0的用户，需要注意以下几点：

1. 移除Bean声明：不再需要显式声明SwaggerUiConfigParameters为Spring Bean
2. 即时创建实例：在需要使用时直接创建新的SwaggerUiConfigParameters实例
3. 依赖调整：确保自定义转换器只依赖必要的配置属性

深入理解设计意图

这一变更体现了Spring框架提倡的"轻量级"和"按需创建"的设计理念。通过避免将SwaggerUiConfigParameters作为单例Bean，可以：

1. 避免潜在的线程安全问题
2. 确保每次请求都能获得最新的配置状态
3. 减少应用启动时的初始化负担

最佳实践

在实际项目中，建议：

1. 保持转换器无状态：将配置相关的状态保存在方法局部变量中
2. 合理复用配置属性：SwaggerUiConfigProperties仍然可以作为Bean注入
3. 考虑性能影响：对于高频访问的端点，可以适当缓存转换结果

总结

springdoc-openapi 2.7.0对Swagger UI配置方式的调整，虽然带来了一定的迁移成本，但从长远来看，这种变化使得框架更加灵活和健壮。理解这一变更背后的设计理念，有助于开发者更好地利用springdoc-openapi构建高质量的API文档系统。