Jinwoo Hwang created GEODE-10500:
------------------------------------
Summary: 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
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:
*
*
*
*
# {*}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)
