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

spbolton · 2025-07-01T20:54:15Z

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

# 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 - Ready for review

Essential authentication and user management APIs
Foundation for all other batches

Batch 2: Content Management Core (14 classes)

PR: #32657 - Draft

Content CRUD operations, versioning, relationships
Content types and field management

Batch 3: Site Architecture & Templates (14 classes)

PR: #32658 - Draft

Site management, templates, containers
File and asset management

Batch 4: System Administration (15 classes)

PR: #32659 - Draft

System configuration and monitoring
Infrastructure management

Batch 5: Publishing & Distribution (13 classes)

PR: #32660 - Draft

Publishing workflows and bundle management
Environment and maintenance operations

Batch 6: Rules Engine & Business Logic (14 classes)

PR: #32661 - Draft

Rules engine components
Business logic and application management

Batch 7: Modern APIs & Specialized Services (17 classes)

PR: #32662 - Draft

AI services and modern APIs
Specialized content and analytics

Batch 8: Legacy & Utility Resources (13 classes)

PR: #32663 - Draft

Legacy APIs and utility functions
Remaining miscellaneous resources

Batch 9: Cleanup and Finalization

PR: #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:

No manual test configuration is needed
Tests grow organically as annotations are added
Full compliance is verified incrementally
No regression in previously annotated resources

📋 Rollout Process

Phase 1: Foundation (This PR)

Merge this PR first - Establishes the infrastructure
Sets up progressive testing framework
Creates annotation system for batch management

Phase 2: Progressive Rollout (Batches 1-8)

Batch 1 (feat(swagger): Add Swagger annotations to Batch 1 - Core Authentication & User Management #32656) - Ready for review after this PR is merged
Batch 2 (feat(swagger): Add Swagger annotations to Batch 2 - Content Management Core #32657) - Remove draft state ONLY after Batch 1 is merged
Batch 3 (feat: add Swagger annotations to Batch 3 - Site Architecture & Templates #32658) - Remove draft state ONLY after Batch 2 is merged
Batch 4 (feat: add Swagger annotations to Batch 4 - System Administration #32659) - Remove draft state ONLY after Batch 3 is merged
Batch 5 (feat: add Swagger annotations to Batch 5 - Publishing & Distribution #32660) - Remove draft state ONLY after Batch 4 is merged
Batch 6 (feat: add Swagger annotations to Batch 6 - Rules Engine & Business Logic #32661) - Remove draft state ONLY after Batch 5 is merged
Batch 7 (feat: add Swagger annotations to Batch 7 - Modern APIs & Specialized Services #32662) - Remove draft state ONLY after Batch 6 is merged
Batch 8 (feat: add Swagger annotations to Batch 8 - Legacy & Utility Resources #32663) - Remove draft state ONLY after Batch 7 is merged

Phase 3: Finalization (Batch 9)

Batch 9 (feat: finalize Swagger annotations implementation - Batch 9 cleanup #32664) - Remove draft state ONLY after Batch 8 is merged
Clean up temporary infrastructure
Complete the implementation

🧪 Testing Strategy

During Rollout

Each batch PR includes comprehensive testing:

# 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:

# 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

Manageable Change Size: 115 resources split into 8 logical batches
Incremental Testing: Tests automatically include new resources as they're annotated
Risk Reduction: Progressive rollout allows for early detection of issues
Clear Dependencies: Each batch builds on previous ones
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	This PR	None
Batch 1	#32656	Ready	This PR
Batch 2	#32657	Draft	Batch 1
Batch 3	#32658	Draft	Batch 2
Batch 4	#32659	Draft	Batch 3
Batch 5	#32660	Draft	Batch 4
Batch 6	#32661	Draft	Batch 5
Batch 7	#32662	Draft	Batch 6
Batch 8	#32663	Draft	Batch 7
Batch 9	#32664	Draft	Batch 8

🤖 Generated with Claude Code

Co-Authored-By: Claude [email protected]

This PR fixes: #32529

alwaysmeticulous · 2025-07-01T20:55:11Z

🤖 No test run has been triggered as your Meticulous project has been deactivated (since you haven't viewed any test results in a while). Click here to reactivate.

_{Last updated for commit c4e4a01. This comment will update as new commits are pushed.}

semgrep-code-dotcms-test · 2025-07-01T21:02:30Z

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

dotCMS/src/main/java/com/dotcms/rest/api/v1/osgi/OSGIResource.java
- L609 - Triage
dotCMS/src/main/java/com/dotcms/rest/OSGIResource.java
- L296 - 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/05c237359f780dba2d79dc2332adcf2a12c122f7/dotCMS/src/main/java/com/dotcms/rest/api/v1/osgi/OSGIResource.java#L583 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 583] multipart</a>"]
        end
        %% Intermediate

        subgraph Traces0[Traces]
            direction TB

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

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

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

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

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

            v7["<a href=https://github.com/dotCMS/core/blob/05c237359f780dba2d79dc2332adcf2a12c122f7/dotCMS/src/main/java/com/dotcms/rest/api/v1/osgi/OSGIResource.java#L607 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 607] 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/05c237359f780dba2d79dc2332adcf2a12c122f7/dotCMS/src/main/java/com/dotcms/rest/api/v1/osgi/OSGIResource.java#L609 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 609] 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
- L1082 - 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/05c237359f780dba2d79dc2332adcf2a12c122f7/dotCMS/src/main/java/com/dotcms/rendering/js/JsResource.java#L126 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 126] bodyMap</a>"]
        end
        %% Intermediate

        subgraph Traces0[Traces]
            direction TB

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

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

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

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

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

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

            v8["<a href=https://github.com/dotCMS/core/blob/05c237359f780dba2d79dc2332adcf2a12c122f7/dotCMS/src/main/java/com/dotcms/rendering/js/JsResource.java#L1067 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1067] 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/05c237359f780dba2d79dc2332adcf2a12c122f7/dotCMS/src/main/java/com/dotcms/rendering/js/JsResource.java#L1082 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1082] 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-code-dotcms-test · 2025-07-01T23:46:07Z

Semgrep found 1 spring-tainted-path-traversal finding:

dotCMS/src/main/java/com/dotcms/rest/ContentResource.java
- L1558 - 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/ContentResource.java</b>"]
        direction LR
        %% Source

        subgraph Source
            direction LR

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

        subgraph Traces0[Traces]
            direction TB

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

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

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

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

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

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

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

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

            v10["<a href=https://github.com/dotCMS/core/blob/16b48e49d9414c94c9e5377b106ee28a3044f30a/dotCMS/src/main/java/com/dotcms/rest/ContentResource.java#L1543 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1543] 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/16b48e49d9414c94c9e5377b106ee28a3044f30a/dotCMS/src/main/java/com/dotcms/rest/ContentResource.java#L1558 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1558] 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.

Semgrep found 1 tainted-file-path finding:

dotCMS/src/main/java/com/dotcms/rest/ContentResource.java
- L1557-1558 - 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/16b48e49d9414c94c9e5377b106ee28a3044f30a/dotCMS/src/main/java/com/dotcms/rest/ContentResource.java#L1359 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1359] multipart</a>"]
        end
        %% Intermediate

        subgraph Traces0[Traces]
            direction TB

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

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

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

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

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

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

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

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

            v10["<a href=https://github.com/dotCMS/core/blob/16b48e49d9414c94c9e5377b106ee28a3044f30a/dotCMS/src/main/java/com/dotcms/rest/ContentResource.java#L1543 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1543] 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/16b48e49d9414c94c9e5377b106ee28a3044f30a/dotCMS/src/main/java/com/dotcms/rest/ContentResource.java#L1557 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1557] 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.

- Modified SwaggerCompliantAnnotationTest to skip resources without @SwaggerCompliant - Updated SwaggerCompliantBatchTest to handle missing annotations gracefully - Enhanced RestEndpointAnnotationComplianceTest with better error handling - Improved SwaggerCompliantCumulativeTest exception handling for class loading - Tests now log warnings for unannotated resources instead of failing - Supports progressive rollout where annotation infrastructure is introduced first 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>

- Removed SwaggerCompliantCumulativeTest as it's not needed for progressive rollout - Test was expecting specific batch counts that don't exist yet - Simplified approach: only test what is actually annotated 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>

cursor

Bug: Incorrect Argument Order in Constructor Calls

The constructors for ResponseEntityTagInodeOperationView and ResponseEntityTagOperationView incorrectly pass the errors list as the first argument to their super() calls. This violates the ResponseEntityView constructor signature, which expects the main data object (e.g., tagInodes, additionalData) as the first argument, followed by errors. The calls should be super(data, errors).

dotCMS/src/main/java/com/dotcms/rest/ResponseEntityTagInodeOperationView.java#L13-L16

core/dotCMS/src/main/java/com/dotcms/rest/ResponseEntityTagInodeOperationView.java

Lines 13 to 16 in 0ca7036

    
           public class ResponseEntityTagInodeOperationView extends ResponseEntityView<List<TagInode>> { 
        
               public ResponseEntityTagInodeOperationView(final List<ErrorEntity> errors, final List<TagInode> tagInodes) { 
        
                   super(errors, tagInodes); 
        
               }

dotCMS/src/main/java/com/dotcms/rest/ResponseEntityTagOperationView.java#L14-L17

core/dotCMS/src/main/java/com/dotcms/rest/ResponseEntityTagOperationView.java

Lines 14 to 17 in 0ca7036

    
           public class ResponseEntityTagOperationView extends ResponseEntityView<Map<String, Object>> { 
        
               public ResponseEntityTagOperationView(final ImmutableList<ErrorEntity> errors, final Map<String, Object> additionalData) { 
        
                   super(errors, additionalData); 
        
               }

Fix in Cursor • Fix in Web

Was this report helpful? Give feedback by reacting with 👍 or 👎

dcolina

Nothing to suggest to this phase. 👍🏽 Green light

dotCMS/src/main/java/com/dotcms/rest/api/v1/event/ResponseEntityEventErrorView.java

jdotcms

Nice job

…ints-missing-it

dotCMS/src/main/java/com/dotcms/rest/api/v1/pushpublish/ResponseEntityFilterErrorView.java

@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 <[email protected]>

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

Add Swagger annotations to endpoints missing it #32529

Closed

vercel bot deployed to Preview – astro-example-uve July 1, 2025 20:55 View deployment

vercel bot deployed to Preview – nextjs-example-uve July 1, 2025 20:55 View deployment

vercel bot deployed to Preview – angular-example-uve July 1, 2025 20:56 View deployment

spbolton force-pushed the issue-32529-add-swagger-annotations-to-endpoints-missing-it branch from 05c2373 to 16b48e4 Compare July 1, 2025 23:33

vercel bot deployed to Preview – astro-example-uve July 1, 2025 23:34 View deployment

vercel bot deployed to Preview – nextjs-example-uve July 1, 2025 23:35 View deployment

vercel bot deployed to Preview – angular-example-uve July 1, 2025 23:36 View deployment

vercel bot deployed to Preview – nextjs-example-uve July 3, 2025 11:57 View deployment

vercel bot deployed to Preview – angular-example-uve July 3, 2025 11:58 View deployment

vercel bot deployed to Preview – astro-example-uve July 3, 2025 11:59 View deployment

spbolton marked this pull request as draft July 3, 2025 12:45

vercel bot deployed to Preview – nextjs-example-uve July 7, 2025 10:57 View deployment

vercel bot deployed to Preview – angular-example-uve July 7, 2025 10:58 View deployment

vercel bot deployed to Preview – astro-example-uve July 7, 2025 10:58 View deployment

spbolton force-pushed the issue-32529-add-swagger-annotations-to-endpoints-missing-it branch from 14def2c to 18f1564 Compare July 7, 2025 11:07

vercel bot deployed to Preview – angular-example-uve July 7, 2025 11:08 View deployment

vercel bot deployed to Preview – astro-example-uve July 7, 2025 11:09 View deployment

vercel bot deployed to Preview – nextjs-example-uve July 7, 2025 11:09 View deployment

spbolton force-pushed the issue-32529-add-swagger-annotations-to-endpoints-missing-it branch from 18f1564 to 555a775 Compare July 7, 2025 11:14

vercel bot deployed to Preview – angular-example-uve July 7, 2025 11:15 View deployment

vercel bot deployed to Preview – astro-example-uve July 7, 2025 11:16 View deployment

vercel bot deployed to Preview – nextjs-example-uve July 7, 2025 11:17 View deployment

spbolton force-pushed the issue-32529-add-swagger-annotations-to-endpoints-missing-it branch from 555a775 to 7e207da Compare July 7, 2025 11:54

vercel bot deployed to Preview – nextjs-example-uve July 7, 2025 11:55 View deployment

vercel bot deployed to Preview – angular-example-uve July 7, 2025 11:56 View deployment

vercel bot deployed to Preview – astro-example-uve July 7, 2025 11:57 View deployment

vercel bot had a problem deploying to Preview – nextjs-example-uve July 10, 2025 10:47 Failure

vercel bot deployed to Preview – astro-example-uve July 10, 2025 10:48 View deployment

spbolton force-pushed the issue-32529-add-swagger-annotations-to-endpoints-missing-it branch 3 times, most recently from f14b7d8 to 3f8c0b1 Compare July 15, 2025 11:43

spbolton changed the title ~~chore(docs): Add Swagger annotations to endpoints missing it (#32529)~~ chore(swagger): Add Swagger annotations Batch Testing Base (#32529) Jul 15, 2025

spbolton mentioned this pull request Jul 15, 2025

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

Merged

spbolton force-pushed the issue-32529-add-swagger-annotations-to-endpoints-missing-it branch from 4b2edac to 985673f Compare July 21, 2025 15:06

spbolton marked this pull request as ready for review July 21, 2025 15:06

This comment was marked as outdated.

Sign in to view

spbolton force-pushed the issue-32529-add-swagger-annotations-to-endpoints-missing-it branch from 985673f to 9825f41 Compare July 22, 2025 09:55

spbolton and others added 4 commits July 23, 2025 15:09

batch init

12e2030

fix tests for non-annotated resources

0f522df

spbolton force-pushed the issue-32529-add-swagger-annotations-to-endpoints-missing-it branch from 9825f41 to 0ca7036 Compare July 23, 2025 14:10

cursor bot reviewed Jul 23, 2025

View reviewed changes

dcolina approved these changes Jul 24, 2025

View reviewed changes

fix up parameter order from cursor bot review

2bbeab4

cursor bot reviewed Jul 24, 2025

View reviewed changes

dotCMS/src/main/java/com/dotcms/rest/api/v1/event/ResponseEntityEventErrorView.java Show resolved Hide resolved

spbolton enabled auto-merge July 24, 2025 14:42

jdotcms approved these changes Jul 24, 2025

View reviewed changes

jcastro-dotcms approved these changes Jul 24, 2025

View reviewed changes

Merge branch 'main' into issue-32529-add-swagger-annotations-to-endpo…

b84eefa

…ints-missing-it

cursor bot reviewed Jul 24, 2025

View reviewed changes

dotCMS/src/main/java/com/dotcms/rest/api/v1/pushpublish/ResponseEntityFilterErrorView.java Show resolved Hide resolved

spbolton added this pull request to the merge queue Jul 24, 2025

Merged via the queue into main with commit a819a45 Jul 24, 2025
41 checks passed

spbolton deleted the issue-32529-add-swagger-annotations-to-endpoints-missing-it branch July 24, 2025 20:47

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

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

Uh oh!

spbolton commented Jul 1, 2025 •

edited by github-actions bot

Loading

Uh oh!

alwaysmeticulous bot commented Jul 1, 2025 •

edited

Loading

Uh oh!

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

Uh oh!

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

Uh oh!

This comment was marked as outdated.

Uh oh!

cursor bot left a comment

Uh oh!

dcolina left a comment

Uh oh!

Uh oh!

jdotcms left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

	public class ResponseEntityTagInodeOperationView extends ResponseEntityView<List<TagInode>> {
	public ResponseEntityTagInodeOperationView(final List<ErrorEntity> errors, final List<TagInode> tagInodes) {
	super(errors, tagInodes);
	}

	public class ResponseEntityTagOperationView extends ResponseEntityView<Map<String, Object>> {
	public ResponseEntityTagOperationView(final ImmutableList<ErrorEntity> errors, final Map<String, Object> additionalData) {
	super(errors, additionalData);
	}

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

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

Uh oh!

Conversation

spbolton commented Jul 1, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

🎯 Progressive Rollout Strategy

🔧 Infrastructure Components

1. @SwaggerCompliant Annotation System

2. Progressive Testing Framework

3. Cumulative Testing Support

📊 Batch Organization (115 REST Resources)

Batch 1: Core Authentication & User Management (15 classes)

Batch 2: Content Management Core (14 classes)

Batch 3: Site Architecture & Templates (14 classes)

Batch 4: System Administration (15 classes)

Batch 5: Publishing & Distribution (13 classes)

Batch 6: Rules Engine & Business Logic (14 classes)

Batch 7: Modern APIs & Specialized Services (17 classes)

Batch 8: Legacy & Utility Resources (13 classes)

Batch 9: Cleanup and Finalization

🔄 Automatic Testing Integration

📋 Rollout Process

Phase 1: Foundation (This PR)

Phase 2: Progressive Rollout (Batches 1-8)

Phase 3: Finalization (Batch 9)

🧪 Testing Strategy

During Rollout

After Completion

📝 Documentation

Batch Documentation

Verification Tests

🎯 Benefits

⚠️ Important Notes

🔗 Related PRs

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

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

Uh oh!

This comment was marked as outdated.

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Bug: Incorrect Argument Order in Constructor Calls

Uh oh!

dcolina left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jdotcms left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

spbolton commented Jul 1, 2025 •

edited by github-actions bot

Loading

alwaysmeticulous bot commented Jul 1, 2025 •

edited

Loading