[
https://issues.apache.org/jira/browse/GEODE-10500?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Jinwoo Hwang updated GEODE-10500:
---------------------------------
Description:
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)
was:
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)
> 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
> Priority: Major
>
> 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)
