feat: finalize Swagger annotations implementation - Batch 9 cleanup by spbolton · Pull Request #32664 · dotCMS/core

spbolton · 2025-07-15T11:48:51Z

Summary

Final cleanup and finalization of the progressive Swagger/OpenAPI annotations implementation - Batch 9

This PR completes the 8-batch progressive rollout by performing final cleanup, removing temporary classes, and ensuring the annotation system is production-ready.

⚠️ IMPORTANT: Batch Rollout Process

This PR is part of a progressive 8-batch rollout strategy.

✅ Batch 1-7: Must be merged first
🔄 Batch 8: Must be merged before this PR
🔄 Batch 9: Remove draft state ONLY after Batch 8 is merged (this PR)

⚠️ Do not remove draft state from this PR until Batch 8 (#32663) has been successfully merged.

Batch 9: Cleanup and Finalization

Theme: Final cleanup, remove temporary classes, and production readiness

Cleanup Tasks

Remove any temporary or test classes that may have been used during development
Clean up any @SwaggerCompliant annotations that are no longer needed
Remove batch-specific test utilities that were used for progressive testing
Update documentation to reflect the completed implementation

Finalization Tasks

Ensure all REST endpoints have proper Swagger annotations
Validate that OpenAPI specification generation is working correctly
Update any configuration files or build processes as needed
Prepare for removal of the progressive testing system

Testing

Final validation of the complete annotation system:

# Test all endpoints without batch filtering
./mvnw test -pl :dotcms-core -Dtest=RestEndpointAnnotationComplianceTest

# Test annotation validation
./mvnw test -pl :dotcms-core -Dtest=RestEndpointAnnotationValidationTest

# Verify OpenAPI spec generation
./mvnw clean install -DskipTests

Impact

✅ Completes the progressive Swagger annotation implementation
✅ Ensures all 115 REST endpoints have proper documentation
✅ Removes temporary batch-specific code
✅ Prepares the system for production use

Dependencies

Depends on: Batch 8 (Legacy & Utility Resources) - feat: add Swagger annotations to Batch 8 - Legacy & Utility Resources #32663
Completes: The progressive Swagger annotation implementation project

Next Steps

After this PR is merged:

The @SwaggerCompliant annotation system can be removed
All tests can run against all endpoints automatically
OpenAPI specification will be fully generated
Documentation will be complete and production-ready

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

semgrep-code-dotcms-test · 2025-07-15T12:01:07Z

Semgrep found 3 spring-tainted-path-traversal findings:

dotCMS/src/main/java/com/dotcms/rest/api/v1/osgi/OSGIResource.java
- L656 - Triage
dotCMS/src/main/java/com/dotcms/rest/OSGIResource.java
- L301 - Triage
dotCMS/src/main/java/com/dotcms/rest/ContentResource.java
- L1561 - Triage

The application builds a file path from potentially untrusted data, which can lead to a path traversal vulnerability. An attacker can manipulate the path which the application uses to access files. If the application does not validate user input and sanitize file paths, sensitive files such as configuration or user data can be accessed, potentially creating or overwriting files. To prevent this vulnerability, validate and sanitize any input that is used to create references to file paths. Also, enforce strict file access controls. For example, choose privileges allowing public-facing applications to access only the required files. In Java, you may also consider using a utility method such as org.apache.commons.io.FilenameUtils.getName(...) to only retrieve the file name from the path.

View Dataflow Graph

flowchart LR
    classDef invis fill:white, stroke: none
    classDef default fill:#e7f5ff, color:#1c7fd6, stroke: none

    subgraph File0["<b>dotCMS/src/main/java/com/dotcms/rest/api/v1/osgi/OSGIResource.java</b>"]
        direction LR
        %% Source

        subgraph Source
            direction LR

            v0["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rest/api/v1/osgi/OSGIResource.java#L630 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 630] multipart</a>"]
        end
        %% Intermediate

        subgraph Traces0[Traces]
            direction TB

            v2["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rest/api/v1/osgi/OSGIResource.java#L630 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 630] multipart</a>"]

            v3["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rest/api/v1/osgi/OSGIResource.java#L638 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 638] multiPartContent</a>"]

            v4["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rest/api/v1/osgi/OSGIResource.java#L641 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 641] requestFiles</a>"]

            v5["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rest/api/v1/osgi/OSGIResource.java#L642 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 642] files</a>"]

            v6["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rest/api/v1/osgi/OSGIResource.java#L654 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 654] uploadedBundleFile</a>"]

            v7["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rest/api/v1/osgi/OSGIResource.java#L654 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 654] uploadedBundleFile</a>"]
        end
            v2 --> v3
            v3 --> v4
            v4 --> v5
            v5 --> v6
            v6 --> v7
        %% Sink

        subgraph Sink
            direction LR

            v1["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rest/api/v1/osgi/OSGIResource.java#L656 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 656] felixUploadFolder + File.separator + uploadedBundleFile.getName()</a>"]
        end
    end
    %% Class Assignment
    Source:::invis
    Sink:::invis

    Traces0:::invis
    File0:::invis

    %% Connections

    Source --> Traces0
    Traces0 --> Sink

If this is a critical or high severity finding, please also link this issue in the #security channel in Slack.

Semgrep found 1 spring-tainted-code-execution finding:

dotCMS/src/main/java/com/dotcms/rendering/js/JsResource.java
- L1109 - Triage

User data flows into a script engine or another means of dynamic code evaluation. This is unsafe and could lead to code injection or arbitrary code execution as a result. Avoid inputting user data into code execution or use proper sandboxing if user code evaluation is necessary.

View Dataflow Graph

flowchart LR
    classDef invis fill:white, stroke: none
    classDef default fill:#e7f5ff, color:#1c7fd6, stroke: none

    subgraph File0["<b>dotCMS/src/main/java/com/dotcms/rendering/js/JsResource.java</b>"]
        direction LR
        %% Source

        subgraph Source
            direction LR

            v0["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rendering/js/JsResource.java#L130 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 130] bodyMap</a>"]
        end
        %% Intermediate

        subgraph Traces0[Traces]
            direction TB

            v2["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rendering/js/JsResource.java#L130 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 130] bodyMap</a>"]

            v3["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rendering/js/JsResource.java#L132 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 132] new</a>"]

            v4["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rendering/js/JsResource.java#L132 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 132] processRequest</a>"]

            v5["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rendering/js/JsResource.java#L1026 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1026] requestParams</a>"]

            v6["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rendering/js/JsResource.java#L1029 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1029] request</a>"]

            v7["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rendering/js/JsResource.java#L1070 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1070] evalJavascript</a>"]

            v8["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rendering/js/JsResource.java#L1094 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1094] request</a>"]
        end
            v2 --> v3
            v3 --> v4
            v4 --> v5
            v5 --> v6
            v6 --> v7
            v7 --> v8
        %% Sink

        subgraph Sink
            direction LR

            v1["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rendering/js/JsResource.java#L1109 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1109] request</a>"]
        end
    end
    %% Class Assignment
    Source:::invis
    Sink:::invis

    Traces0:::invis
    File0:::invis

    %% Connections

    Source --> Traces0
    Traces0 --> Sink

If this is a critical or high severity finding, please also link this issue in the #security channel in Slack.

Semgrep found 1 tainted-file-path finding:

dotCMS/src/main/java/com/dotcms/rest/ContentResource.java
- L1560-1561 - Triage

Detected user input controlling a file path. An attacker could control the location of this file, to include going backwards in the directory with '../'. To address this, ensure that user-controlled variables in file paths are sanitized. You may also consider using a utility method such as org.apache.commons.io.FilenameUtils.getName(...) to only retrieve the file name from the path.

View Dataflow Graph

flowchart LR
    classDef invis fill:white, stroke: none
    classDef default fill:#e7f5ff, color:#1c7fd6, stroke: none

    subgraph File0["<b>dotCMS/src/main/java/com/dotcms/rest/ContentResource.java</b>"]
        direction LR
        %% Source

        subgraph Source
            direction LR

            v0["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rest/ContentResource.java#L1362 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1362] multipart</a>"]
        end
        %% Intermediate

        subgraph Traces0[Traces]
            direction TB

            v2["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rest/ContentResource.java#L1362 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1362] multipart</a>"]

            v3["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rest/ContentResource.java#L1366 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1366] multipartPUTandPOST</a>"]

            v4["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rest/ContentResource.java#L1415 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1415] multipart</a>"]

            v5["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rest/ContentResource.java#L1430 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1430] part</a>"]

            v6["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rest/ContentResource.java#L1430 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1430] part</a>"]

            v7["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rest/ContentResource.java#L1510 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1510] processFile</a>"]

            v8["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rest/ContentResource.java#L1542 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1542] part</a>"]

            v9["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rest/ContentResource.java#L1545 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1545] badFileName</a>"]

            v10["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rest/ContentResource.java#L1546 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1546] filename</a>"]
        end
            v2 --> v3
            v3 --> v4
            v4 --> v5
            v5 --> v6
            v6 --> v7
            v7 --> v8
            v8 --> v9
            v9 --> v10
        %% Sink

        subgraph Sink
            direction LR

            v1["<a href=https://github.com/dotCMS/core/blob/0d88913ffa494c9de2cb6cb724cb4d1c639f18aa/dotCMS/src/main/java/com/dotcms/rest/ContentResource.java#L1560 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1560] new File(<br>                    tmpFolder.getAbsolutePath() + File.separator + filename)</a>"]
        end
    end
    %% Class Assignment
    Source:::invis
    Sink:::invis

    Traces0:::invis
    File0:::invis

    %% Connections

    Source --> Traces0
    Traces0 --> Sink

If this is a critical or high severity finding, please also link this issue in the #security channel in Slack.

…32561) ## Summary This PR establishes the progressive testing infrastructure for Swagger/OpenAPI annotations implementation across 115 REST endpoints in dotCMS. ***Note for reviewers.*** Most of the files in this PR add new view classes that are not yet used in this PR but are added in preparation and use of the individual Resource classes that we change in upcoming batches. We do not need to deeply review these new classes at this time as they will have no impact on functionality at this time. In these batches we can also look at the openapi.yml that now gets generated and included in the commit for any resource changes. In this PR it confirms we are only changing and adding tag descriptions providing the categories for the upcoming batch changes. The main part of this PR is the additional test changes which are set to identify using an annotation the upcoming changed resource files and will test them when updated. In this PR these will essentially skip and do nothing. ## 🎯 Progressive Rollout Strategy This PR creates the foundation for a **9-batch progressive rollout** of Swagger annotations. The annotations will be added incrementally to make the large change manageable and allow for thorough testing at each stage. This first PR does not actually modify any or the resources. It provides the testing framework that will pick up the updated resources when they are added. It also adds a few underlying fixes and additional View classes that will be used by the updated Resource classes when they are added but on their own will have no impact. ## 🔧 Infrastructure Components ### 1. @SwaggerCompliant Annotation System - **File**: `dotCMS/src/main/java/com/dotcms/rest/annotation/SwaggerCompliant.java` - **Purpose**: Marks REST resource classes that have been updated with proper Swagger annotations - **Features**: - Batch numbering system (1-8) - Version tracking - Descriptive documentation ### 2. Progressive Testing Framework - **Updated**: `RestEndpointAnnotationComplianceTest.java` - **Updated**: `RestEndpointAnnotationValidationTest.java` - **Feature**: Automatic class discovery based on `@SwaggerCompliant` annotations - **Benefit**: Tests automatically include newly annotated classes when PRs are merged ### 3. Cumulative Testing Support ```bash # Test only classes from batches 1-3 (cumulative) ./mvnw test -pl :dotcms-core -Dtest=RestEndpointAnnotationComplianceTest -Dtest.batch.max=3 # Test all annotated classes (when annotation is present) ./mvnw test -pl :dotcms-core -Dtest=RestEndpointAnnotationComplianceTest ``` ## 📊 Batch Organization (115 REST Resources) ### Batch 1: Core Authentication & User Management (15 classes) **PR**: [#32656](#32656) - **Ready for review** - Essential authentication and user management APIs - Foundation for all other batches ### Batch 2: Content Management Core (14 classes) **PR**: [#32657](#32657) - **Draft** - Content CRUD operations, versioning, relationships - Content types and field management ### Batch 3: Site Architecture & Templates (14 classes) **PR**: [#32658](#32658) - **Draft** - Site management, templates, containers - File and asset management ### Batch 4: System Administration (15 classes) **PR**: [#32659](#32659) - **Draft** - System configuration and monitoring - Infrastructure management ### Batch 5: Publishing & Distribution (13 classes) **PR**: [#32660](#32660) - **Draft** - Publishing workflows and bundle management - Environment and maintenance operations ### Batch 6: Rules Engine & Business Logic (14 classes) **PR**: [#32661](#32661) - **Draft** - Rules engine components - Business logic and application management ### Batch 7: Modern APIs & Specialized Services (17 classes) **PR**: [#32662](#32662) - **Draft** - AI services and modern APIs - Specialized content and analytics ### Batch 8: Legacy & Utility Resources (13 classes) **PR**: [#32663](#32663) - **Draft** - Legacy APIs and utility functions - Remaining miscellaneous resources ### Batch 9: Cleanup and Finalization **PR**: [#32664](#32664) - **Draft** - Remove temporary testing infrastructure - Final cleanup and production readiness ## 🔄 Automatic Testing Integration **Key Feature**: When annotations are added to REST resources, they **automatically trigger testing** of those resources when the PRs are merged. - ✅ **Before annotation**: Resource is not tested by compliance tests - ✅ **After annotation**: Resource is automatically discovered and tested - ✅ **Cumulative**: Tests run against all previously annotated resources plus new ones This ensures that: 1. No manual test configuration is needed 2. Tests grow organically as annotations are added 3. Full compliance is verified incrementally 4. No regression in previously annotated resources ## 📋 Rollout Process ### Phase 1: Foundation (This PR) 1. **Merge this PR first** - Establishes the infrastructure 2. Sets up progressive testing framework 3. Creates annotation system for batch management ### Phase 2: Progressive Rollout (Batches 1-8) 1. **Batch 1** (#32656) - Ready for review after this PR is merged 2. **Batch 2** (#32657) - Remove draft state ONLY after Batch 1 is merged 3. **Batch 3** (#32658) - Remove draft state ONLY after Batch 2 is merged 4. **Batch 4** (#32659) - Remove draft state ONLY after Batch 3 is merged 5. **Batch 5** (#32660) - Remove draft state ONLY after Batch 4 is merged 6. **Batch 6** (#32661) - Remove draft state ONLY after Batch 5 is merged 7. **Batch 7** (#32662) - Remove draft state ONLY after Batch 6 is merged 8. **Batch 8** (#32663) - Remove draft state ONLY after Batch 7 is merged ### Phase 3: Finalization (Batch 9) 1. **Batch 9** (#32664) - Remove draft state ONLY after Batch 8 is merged 2. Clean up temporary infrastructure 3. Complete the implementation ## 🧪 Testing Strategy ### During Rollout Each batch PR includes comprehensive testing: ```bash # Test cumulative batches (e.g., for Batch 3) ./mvnw test -pl :dotcms-core -Dtest=RestEndpointAnnotationComplianceTest -Dtest.batch.max=3 ``` ### After Completion All tests run against all endpoints automatically: ```bash # No batch filtering needed - all annotated resources tested ./mvnw test -pl :dotcms-core -Dtest=RestEndpointAnnotationComplianceTest ``` ## 📝 Documentation ### Batch Documentation - **File**: `SWAGGER_COMPLIANT_BATCHES.md` - **Contains**: Detailed breakdown of all 115 resources across 8 batches - **Usage**: Reference for understanding batch organization and testing ### Verification Tests - **File**: `SwaggerCompliantAnnotationTest.java` - **File**: `SwaggerCompliantBatchTest.java` - **Purpose**: Validate annotation structure and batch organization ## 🎯 Benefits 1. **Manageable Change Size**: 115 resources split into 8 logical batches 2. **Incremental Testing**: Tests automatically include new resources as they're annotated 3. **Risk Reduction**: Progressive rollout allows for early detection of issues 4. **Clear Dependencies**: Each batch builds on previous ones 5. **Automated Discovery**: No manual test configuration required ## ⚠️ Important Notes - **Merge Order**: This PR must be merged before any batch PRs - **Draft Management**: Batch PRs should remain in draft until predecessor is merged - **Testing**: Annotations automatically trigger testing when resources are merged - **Dependencies**: Each batch depends on all previous batches being merged ## 🔗 Related PRs | Batch | PR | Status | Dependencies | |-------|----|---------|--------------| | Foundation | [#32561](#32561) | **This PR** | None | | Batch 1 | [#32656](#32656) | Ready | This PR | | Batch 2 | [#32657](#32657) | Draft | Batch 1 | | Batch 3 | [#32658](#32658) | Draft | Batch 2 | | Batch 4 | [#32659](#32659) | Draft | Batch 3 | | Batch 5 | [#32660](#32660) | Draft | Batch 4 | | Batch 6 | [#32661](#32661) | Draft | Batch 5 | | Batch 7 | [#32662](#32662) | Draft | Batch 6 | | Batch 8 | [#32663](#32663) | Draft | Batch 7 | | Batch 9 | [#32664](#32664) | Draft | Batch 8 | 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>

@tag

…on & User Management (#32656) ## Summary Progressive implementation of Swagger/OpenAPI annotations for REST endpoints - Batch 1 This PR adds comprehensive Swagger annotations to **15 REST resource classes** focused on core authentication and user management APIs that most applications depend on. ## 🔗 Foundation Dependency **⚠️ This PR depends on the infrastructure established in PR #32561** - **Foundation PR**: [#32561 - Progressive Swagger annotations infrastructure](#32561) - **Requirement**: PR #32561 must be merged before this PR can be reviewed/merged - **Why**: This PR uses the `@SwaggerCompliant` annotation and progressive testing framework created in #32561 ## ⚠️ IMPORTANT: Batch Rollout Process **This PR is part of a progressive 8-batch rollout strategy established in PR #32561.** - 🔧 **Foundation**: [PR #32561](#32561) - Must be merged first - ✅ **Batch 1**: Ready for review after foundation is merged (this PR) - ⏳ **Batch 2**: [PR #32657](#32657) - Keep in draft until Batch 1 is merged - ⏳ **Batch 3-8**: Keep in draft until previous batch is merged - ⏳ **Batch 9**: [PR #32664](#32664) - Keep in draft until Batch 8 is merged **Do not remove draft state from subsequent batches until the previous batch has been successfully merged.** ## 🎯 Automatic Testing Integration This PR leverages the infrastructure from #32561 to enable **automatic testing**: - ✅ **Before this PR**: These 15 resources are not tested by compliance tests - ✅ **After this PR**: Resources are automatically discovered and tested via `@SwaggerCompliant` annotations - ✅ **Cumulative**: Future batches will test these resources plus their new ones ```bash # Test only Batch 1 classes (using infrastructure from #32561) ./mvnw test -pl :dotcms-core -Dtest=RestEndpointAnnotationComplianceTest -Dtest.batch.max=1 ``` ## Batch 1: Core Authentication & User Management (15 classes) **Theme**: Essential user and authentication APIs that most applications depend on ### Authentication Resources (7 classes) - `AuthenticationResource` - Core authentication endpoints - `ApiTokenResource` - API token management - `LoginFormResource` - Login form handling - `LogoutResource` - User logout functionality - `CreateJsonWebTokenResource` - JWT token creation - `ForgotPasswordResource` - Password reset requests - `ResetPasswordResource` - Password reset completion ### User Management Resources (3 classes) - `UserResource` - User CRUD operations - `PersonaResource` - User persona management - `PersonalizationResource` - User personalization settings ### System Role Resources (2 classes) - `RoleResource` - Role management - `PermissionResource` - Permission handling ### Legacy User Resources (3 classes) - `UserResource` (legacy) - Legacy user operations - `RoleResource` (legacy) - Legacy role operations - `DotSamlResource` - SAML authentication ## 🧪 Testing Strategy Uses the progressive testing framework established in #32561: ```bash # Test only Batch 1 classes (after #32561 is merged) ./mvnw test -pl :dotcms-core -Dtest=RestEndpointAnnotationComplianceTest -Dtest.batch.max=1 # Test annotation validation ./mvnw test -pl :dotcms-core -Dtest=RestEndpointAnnotationValidationTest -Dtest.batch.max=1 ``` ## 📋 Example Annotation Usage This PR adds `@SwaggerCompliant` annotations (from #32561) to mark resources as properly documented: ```java @SwaggerCompliant(value = "Core authentication and user management APIs", batch = 1) @tag(name = "Authentication") @path("/v1/authentication") public class AuthenticationResource { // Properly annotated endpoints... } ``` ## 🎯 Impact - ✅ Improves API documentation for core authentication flows - ✅ Enables automatic testing of these 15 resources (via #32561 infrastructure) - ✅ Enables better developer experience with OpenAPI spec generation - ✅ Maintains backward compatibility - ✅ Follows established annotation patterns and standards ## 📊 Progress Tracking This PR is **Batch 1 of 8** in the progressive rollout: - **Total Resources**: 115 across 8 batches - **This Batch**: 15 resources (13% of total) - **Next**: Batch 2 (Content Management Core) - 14 resources ## 🔗 Related PRs - **Foundation**: [#32561 - Progressive Swagger annotations infrastructure](#32561) ← **Must merge first** - **Next**: [#32657 - Batch 2 (Content Management Core)](#32657) - **Complete chain**: See PR #32561 for full rollout plan ## ⚠️ Merge Requirements 1. **Foundation PR #32561 must be merged first** 2. This PR can then be reviewed and merged 3. After this PR is merged, remove draft state from Batch 2 PR #32657 4. Continue sequential rollout through Batch 8 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

github-actions · 2025-08-24T02:14:59Z

This PR is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 7 days.

github-actions · 2025-09-01T02:15:05Z

This PR was closed because it has been stalled with no activity.

spbolton added 9 commits July 15, 2025 12:16

batch init

3f8c0b1

Batch 1 resources

23507a1

Batch 2 resources

6947d76

Batch 3 resources

2dc53b4

Batch 4 resources

da0fa2a

Batch 5 resources

f3373bc

Batch 6 resources

976be40

Batch 7 resources

61e7f81

Batch 8 resources

f7aff75

github-actions bot mentioned this pull request Jul 15, 2025

Add Swagger annotations to endpoints missing it #32529

Closed

This was referenced Jul 15, 2025

feat: add Swagger annotations to Batch 8 - Legacy & Utility Resources #32663

Closed

chore(swagger): Add Swagger annotations Batch Testing Base (#32529) #32561

Merged

spbolton mentioned this pull request Jul 15, 2025

feat(swagger): Add Swagger annotations to Batch 1 - Core Authentication & User Management #32656

Merged

Batch 9 cleanup

4366f1a

spbolton force-pushed the issue-32529-batch-9 branch from 0d88913 to 4366f1a Compare July 24, 2025 13:43

github-actions bot added the stale label Aug 24, 2025

github-actions bot closed this Sep 1, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: finalize Swagger annotations implementation - Batch 9 cleanup#32664

feat: finalize Swagger annotations implementation - Batch 9 cleanup#32664
spbolton wants to merge 10 commits intomainfrom
issue-32529-batch-9

spbolton commented Jul 15, 2025 •

edited

Loading

Uh oh!

semgrep-code-dotcms-test bot commented Jul 15, 2025

Uh oh!

github-actions bot commented Aug 24, 2025

Uh oh!

github-actions bot commented Sep 1, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

spbolton commented Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

⚠️ IMPORTANT: Batch Rollout Process

Batch 9: Cleanup and Finalization

Cleanup Tasks

Finalization Tasks

Testing

Impact

Dependencies

Next Steps

Uh oh!

semgrep-code-dotcms-test bot commented Jul 15, 2025

Uh oh!

github-actions bot commented Aug 24, 2025

Uh oh!

github-actions bot commented Sep 1, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

spbolton commented Jul 15, 2025 •

edited

Loading