[
https://issues.apache.org/jira/browse/GEODE-10500?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Jinwoo Hwang updated GEODE-10500:
---------------------------------
Fix Version/s: 2.0.0
> Migrate SpringDoc from 1.6.8 to 2.3.0 for Spring Framework 6.x Compatibility
> ----------------------------------------------------------------------------
>
> Key: GEODE-10500
> URL: https://issues.apache.org/jira/browse/GEODE-10500
> Project: Geode
> Issue Type: Improvement
> Reporter: Jinwoo Hwang
> Assignee: Jinwoo Hwang
> Priority: Major
> Fix For: 2.0.0
>
>
> h3. *Summary*
> Upgrade SpringDoc OpenAPI from version 1.6.8 to 2.3.0 to resolve
> compatibility issues with Spring Framework 6.1.1 and ensure proper API
> documentation functionality in Geode's web management and REST API modules.
> ----
> h3. *Background*
> Apache Geode currently uses SpringDoc 1.6.8 for generating OpenAPI
> documentation in the geode-web-management and geode-web-api modules.
> Following the upgrade to Spring Framework 6.1.1 (from 5.3.21), SpringDoc 1.x
> is no longer compatible with the newer Spring Framework version, causing
> integration test failures and runtime errors.
> *Root Cause Analysis:*
> * Spring Framework 6.x removed the
> {{LocalVariableTableParameterNameDiscoverer}} class that SpringDoc 1.x
> depends on
> * SpringDoc 1.x series only supports Spring Framework 5.x and earlier
> versions
> * SpringDoc 2.x series is specifically designed for Spring Framework 6.x and
> Spring Boot 3.x compatibility
> ----
> h3. *Current Issues*
> * {*}Integration Test Failures{*}: DocLinksControllerRestIntegrationTest and
> GatewayManagementIntegrationTest fail with:
>
> java.lang.NoClassDefFoundError:
> org/springframework/core/LocalVariableTableParameterNameDiscoverer
>
>
> * {*}Spring Context Loading Errors{*}: SpringDoc auto-configuration fails to
> load properly with Spring 6.x, causing Bean instantiation exceptions
> * {*}Deprecated API Usage{*}: SpringDoc 1.x uses deprecated Spring Framework
> APIs that have been removed in version 6.x
> ----
> h3. *Scope of Migration*
> The migration affects the following modules and components:
> *Affected Modules:*
> * geode-web-management
> * geode-web-api
> * geode-management
> *Key Components to Update:*
> # {*}Dependency Management{*}: Update version constraints in
> DependencyConstraints.groovy
> # {*}Artifact Names{*}: Migrate from springdoc-openapi-ui to
> springdoc-openapi-starter-webmvc-ui
> # {*}Java Imports{*}: Update package paths (e.g.,
> org.springdoc.core.GroupedOpenApi → org.springdoc.core.models.GroupedOpenApi)
> # {*}Spring Configuration{*}: Update auto-configuration class registrations
> for SpringDoc 2.x
> # {*}Security Configuration{*}: Update web security paths for new SpringDoc
> UI resource locations
> # {*}Build Scripts{*}: Update all build.gradle files referencing SpringDoc
> dependencies
> ----
> h3. *Technical Impact Analysis*
> *Breaking Changes Expected:*
> * Package structure changes in SpringDoc 2.x require import statement updates
> * Auto-configuration class names have changed between versions
> * Web resource paths for Swagger UI have been reorganized
> * Some SpringDoc configuration properties may have been renamed or
> restructured
> *Integration Points:*
> * Spring Security path configurations for API documentation endpoints
> * Custom Swagger configuration beans and OpenAPI definitions
> * Web application context initialization for documentation serving
> * Maven/Gradle dependency resolution and classpath management
> ----
> h3. *Risk Assessment*
> *High Risk Areas:*
> * API documentation may become temporarily unavailable during migration
> * Custom OpenAPI configurations may need adjustment for SpringDoc 2.x
> * Integration tests dependent on Swagger UI functionality may require updates
> * Path mappings conflicts between SpringDoc and existing Geode controllers
> *Mitigation Strategies:*
> * Comprehensive testing of API documentation functionality post-migration
> * Validation of all OpenAPI endpoint availability and content accuracy
> * Integration test execution to ensure no regression in REST API
> functionality
> * Documentation update for any changed API documentation access patterns
> ----
> h3. *Dependencies*
> * {*}Prerequisite{*}: Spring Framework 6.1.1 upgrade must be completed
> * {*}Related{*}: Spring Security 6.x configuration updates
> * {*}Impact{*}: Any downstream consumers of Geode's API documentation
> ----
> h3. *Acceptance Criteria*
> # All SpringDoc dependencies successfully upgraded to version 2.3.0
> # Integration tests (DocLinksControllerRestIntegrationTest,
> GatewayManagementIntegrationTest) pass without errors
> # API documentation endpoints remain accessible and functional
> # No runtime errors related to SpringDoc/Spring Framework compatibility
> # Swagger UI loads properly with correct API documentation content
> # No regression in REST API functionality or documentation quality
> ----
> h3. *Technical Debt*
> This migration addresses technical debt accumulated from:
> * Deferred dependency updates during the Spring Framework upgrade
> * Incompatible library version combinations in the current dependency matrix
> * Usage of deprecated Spring Framework APIs through transitive dependencies
> *Post-Migration Benefits:*
> * Full compatibility with Spring Framework 6.x ecosystem
> * Access to SpringDoc 2.x performance improvements and new features
> * Elimination of deprecated API usage warnings
> * Future-proofed API documentation infrastructure
> * Improved Spring Boot 3.x compatibility (for potential future upgrades)
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
