[jira] [Assigned] (GEODE-10500) Migrate SpringDoc from 1.6.8 to 2.3.0 for Spring Framework 6.x Compatibility

["Jinwoo Hwang (Jira)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/GEODE-10500?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Jinwoo Hwang reassigned GEODE-10500:
------------------------------------

    Assignee: Jinwoo Hwang

> 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
>
> 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)