feat(swagger): Add Swagger annotations to Batch 2 - Content Management Core #32657

spbolton · 2025-07-15T11:46:57Z

Summary

Progressive implementation of Swagger/OpenAPI annotations for REST endpoints - Batch 2

This PR adds comprehensive Swagger annotations to 14 REST resource classes focused on primary content creation, editing, and management APIs.

⚠️ IMPORTANT: Batch Rollout Process

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

✅ Batch 1: Must be merged first
🔄 Batch 2: Remove draft state ONLY after Batch 1 is merged (this PR)
⏳ Batch 3-8: Keep in draft until previous batch is merged
⏳ Batch 9: Keep in draft until Batch 8 is merged

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

Batch 2: Content Management Core (14 classes)

Theme: Primary content creation, editing, and management APIs

Content Resources (6 classes)

ContentResource - Core content CRUD operations
ContentVersionResource - Content versioning
ContentRelationshipsResource - Content relationships
ContentReportResource - Content reporting
ResourceLinkResource - Resource linking
ContentImportResource - Content import functionality

Content Type Resources (4 classes)

ContentTypeResource - Content type management
FieldResource - Field management
FieldVariableResource - Field variable handling
FieldTypeResource - Field type definitions

Workflow Resources (1 class)

WorkflowResource - Workflow management

Categories & Tags (2 classes)

CategoriesResource - Category management
TagResource (v2) - Tag management

Legacy Content Resources (1 class)

ContentResource (legacy) - Legacy content operations

Testing

Progressive testing approach using the @SwaggerCompliant annotation system:

# Test Batches 1-2 (cumulative)
./mvnw test -pl :dotcms-core -Dtest=RestEndpointAnnotationComplianceTest -Dtest.batch.max=2

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

Impact

✅ Improves API documentation for content management workflows
✅ Enables better developer experience with content APIs
✅ Maintains backward compatibility
✅ Follows established annotation patterns and standards

Dependencies

Depends on: Batch 1 (Core Authentication & User Management) - feat(swagger): Add Swagger annotations to Batch 1 - Core Authentication & User Management #32656
Next: Batch 3 (Site Architecture & Templates) - feat: add Swagger annotations to Batch 3 - Site Architecture & Templates #32658

🤖 Generated with Claude Code

Co-Authored-By: Claude [email protected]

semgrep-code-dotcms-test · 2025-07-15T11:55:30Z

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

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/ContentResource.java</b>"]
        direction LR
        %% Source

        subgraph Source
            direction LR

            v0["<a href=https://github.com/dotCMS/core/blob/6947d76291bbc4057625c367785fc2abf4945a79/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/6947d76291bbc4057625c367785fc2abf4945a79/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/6947d76291bbc4057625c367785fc2abf4945a79/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/6947d76291bbc4057625c367785fc2abf4945a79/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/6947d76291bbc4057625c367785fc2abf4945a79/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/6947d76291bbc4057625c367785fc2abf4945a79/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/6947d76291bbc4057625c367785fc2abf4945a79/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/6947d76291bbc4057625c367785fc2abf4945a79/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/6947d76291bbc4057625c367785fc2abf4945a79/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/6947d76291bbc4057625c367785fc2abf4945a79/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/6947d76291bbc4057625c367785fc2abf4945a79/dotCMS/src/main/java/com/dotcms/rest/ContentResource.java#L1561 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1561] 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
- 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/6947d76291bbc4057625c367785fc2abf4945a79/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/6947d76291bbc4057625c367785fc2abf4945a79/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/6947d76291bbc4057625c367785fc2abf4945a79/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/6947d76291bbc4057625c367785fc2abf4945a79/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/6947d76291bbc4057625c367785fc2abf4945a79/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/6947d76291bbc4057625c367785fc2abf4945a79/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/6947d76291bbc4057625c367785fc2abf4945a79/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/6947d76291bbc4057625c367785fc2abf4945a79/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/6947d76291bbc4057625c367785fc2abf4945a79/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/6947d76291bbc4057625c367785fc2abf4945a79/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/6947d76291bbc4057625c367785fc2abf4945a79/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 <[email protected]> --------- Co-authored-by: Claude <[email protected]>

@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 · 2025-09-28T02:11:34Z

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-10-06T02:06:11Z

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

… app.

jdcmsd · 2025-12-16T17:29:25Z

I was able to replace the merge with a rebase using git rebase --rebase-merges origin/main, confirmed updated version of relevant resource files, kept origin/main version of everything else, and did a --force-with-lease push. This should be much nicer than last week's attempt.

spbolton · 2025-12-17T11:58:19Z

Looks ok now by me after removing a couple of frontend files that got in with duplicated methods, but I cannot approve myself as I am set as the author.

nollymar · 2025-12-19T00:22:03Z

dotCMS/src/main/java/com/dotcms/rest/api/v1/categories/CategoriesResource.java

    public final HierarchyShortCategoriesResponseView getHierarchy(@Context final HttpServletRequest httpRequest,
                                       @Context final HttpServletResponse httpResponse,
-                                       final CategoryKeysForm form) throws DotDataException {
+                                       @io.swagger.v3.oas.annotations.parameters.RequestBody(description = "Category keys form containing array of category keys", required = true) final CategoryKeysForm form) throws DotDataException {


you can remove the io.swagger.v3.oas.annotations.parameters from the RequestBody as it is already imported in the class. It would also make the documentation less verbose

Will adopt this change in the next commit.

nollymar · 2025-12-19T00:22:26Z

dotCMS/src/main/java/com/dotcms/rest/api/v1/categories/CategoriesResource.java

    public final Response saveNew(@Context final HttpServletRequest httpRequest,
            @Context final HttpServletResponse httpResponse,
-            final CategoryForm categoryForm)
+            @io.swagger.v3.oas.annotations.parameters.RequestBody(description = "Category form with name and properties", required = true) final CategoryForm categoryForm)


nollymar · 2025-12-19T00:23:03Z

dotCMS/src/main/java/com/dotcms/rest/api/v1/categories/CategoriesResource.java

    public final Response save(@Context final HttpServletRequest httpRequest,
            @Context final HttpServletResponse httpResponse,
-            final CategoryForm categoryForm) throws DotDataException, DotSecurityException {
+            @io.swagger.v3.oas.annotations.parameters.RequestBody(description = "Category form with updated properties including inode", required = true) final CategoryForm categoryForm) throws DotDataException, DotSecurityException {


here too, and in the rest of the class

nollymar · 2025-12-19T00:35:40Z

dotCMS/src/main/java/com/dotcms/rest/ContentResource.java

                try {
-                    processJSON(contentlet, part.getEntityAs(InputStream.class));
+                    // Read and parse JSON once to avoid "Stream closed" error
+                    final Map<String, Object> jsonMap = WebResource.processJSON(part.getEntityAs(InputStream.class));


why was this changed?

This is one of the Claude changes; comment says it's to avoid an error, but I would see if @spbolton can clarify it.

nollymar · 2025-12-19T00:36:15Z

dotCMS/src/main/java/com/dotcms/rest/ContentResource.java


                        String callback = init.getParamsMap().get(RESTParams.CALLBACK.getValue());
-                        return Response.ok(callback + "(" + result + ")", "application/javascript")
+                        return Response.ok(callback + "(" + result + ")")


why was this changed?

Based on a previous conversation, I think there are some cases where we needlessly add a javascript return type even though there's no practical reason for it, given the possible API responses. But I'll likewise defer to @spbolton here.

nollymar · 2025-12-19T00:38:51Z

dotCMS/src/main/java/com/dotcms/rest/api/v1/categories/CategoriesResource.java

-
-            stringReader = new StringReader(content);
-            bufferedReader = new BufferedReader(stringReader);
+            bufferedReader = new BufferedReader(new InputStreamReader(fileInputStream, StandardCharsets.UTF_8));


why was this changed?

Looks like it corresponds to a refactor that replaces a bunch of args with a form that reimagines a file component as an input stream. As to why, I genuinely have no idea. @spbolton ?

Edit: Maybe it's to make the endpoint more paradigmatic of a POST endpoint, to depend upon a single form payload instead of params?

I think it's fine, we're eliminating an unnecessary step. Buffering in the StringReading, instead, we're going straight to get the contents from the fileInputStream

fabrizzio-dotCMS · 2025-12-19T14:54:57Z

dotCMS/src/main/java/com/dotcms/rest/api/v1/categories/CategoriesResource.java

-            @FormDataParam("filter") String filter,
-            @FormDataParam("exportType") String exportType,
-            @FormDataParam("contextInode") String contextInode) throws IOException {
+            @Parameter(hidden = true) @BeanParam final CategoryImportData form) throws IOException {


nice little enhancement

fabrizzio-dotCMS

I left a couple of comments
It would be great if you could verify that APIPlayGround is loading correctly
From previous experience, I suspect that documenting Beans that take a file or an InputStream can be somewhat problematic. I think I broke the CLI when I did that myself
I saw you removed @produces("application/octet-stream") in a couple of places, just make sure that those endpoints are not returning an outStream or something

fabrizzio-dotCMS · 2025-12-19T14:58:24Z

dotCMS/src/main/java/com/dotcms/rest/api/v1/categories/CategoryImportData.java

+
+    @FormDataParam("file")
+    @JsonProperty("file")
+    @Schema(name = "file", description = "CSV file containing categories to import", type = "string", format = "binary")


Have you been able to load this into the API Playground?
Once, I attempted to document an InputStream setter and it broke the playground

Interesting! So, on the Playground end, it seems to be good:

And it generates a 200 when I import a category export CSV. But no new categories appear; system logs indicate a null pointer exception.

[22/12/25 14:35:28:333 GMT] ERROR categories.CategoriesResource: Error importing categories java.lang.NullPointerException: null at java.base/java.io.Reader.<init>(Reader.java:168) ~[?:?] at java.base/java.io.InputStreamReader.<init>(InputStreamReader.java:123) ~[?:?] at com.dotcms.rest.api.v1.categories.CategoriesResource.processImport(CategoriesResource.java:942) ~[?:?] at com.dotcms.rest.api.v1.categories.CategoriesResource.importCategories(CategoriesResource.java:908) ~[?:?] at java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(DirectMethodHandleAccessor.java:103) ~[?:?] at java.base/java.lang.reflect.Method.invoke(Method.java:580) ~[?:?] at org.glassfish.jersey.server.model.internal.ResourceMethodInvocationHandlerFactory.lambda$static$0(ResourceMethodInvocationHandlerFactory.java:52) ~[?:?] at org.glassfish.jersey.server.model.internal.AbstractJavaResourceMethodDispatcher$1.run(AbstractJavaResourceMethodDispatcher.java:124) ~[?:?] at org.glassfish.jersey.server.model.internal.AbstractJavaResourceMethodDispatcher.invoke(AbstractJavaResourceMethodDispatcher.java:167) ~[?:?] at org.glassfish.jersey.server.model.internal.JavaResourceMethodDispatcherProvider$ResponseOutInvoker.doDispatch(JavaResourceMethodDispatcherProvider.java:176) ~[?:?] at org.glassfish.jersey.server.model.internal.AbstractJavaResourceMethodDispatcher.dispatch(AbstractJavaResourceMethodDispatcher.java:79) ~[?:?] at org.glassfish.jersey.server.model.ResourceMethodInvoker.invoke(ResourceMethodInvoker.java:469) ~[?:?] at org.glassfish.jersey.server.model.ResourceMethodInvoker.apply(ResourceMethodInvoker.java:391) ~[?:?] at org.glassfish.jersey.server.model.ResourceMethodInvoker.apply(ResourceMethodInvoker.java:80) ~[?:?] at org.glassfish.jersey.server.ServerRuntime$1.run(ServerRuntime.java:253) ~[?:?] ...

fabrizzio-dotCMS · 2025-12-19T15:03:59Z

dotCMS/src/main/java/com/dotcms/rest/api/v1/workflow/WorkflowActionMultipartSchema.java

+    @Schema(description = "List of binary field variables. The uploaded files in 'file' should correspond by index to these field variables.", example = "[\"binaryImage\", \"binaryDocument\"]")
+    public List<String> binaryFields;
+
+    @FormParam("file")


Same piece of advice, perhaps I didn't apply the tags correctly, but once I broke the API plugin trying to doc Files. So double-check before pushing

I'm a little uncertain of exactly what it's looking for. If I tell the {actionId}/firemultipart to upload an image and specify the JSON {\n "contentType": "DotAsset",\n "title": "aaa111"\n}, I get "error": "dotcms.api.error.bad_request: The content type or base type, is not set or is invalid". Checked to confirm DotAsset is the relevant content type variable name. (Also tried dotAsset, as below)

fabrizzio-dotCMS · 2025-12-19T15:10:29Z

dotCMS/src/main/java/com/dotcms/rest/api/v1/workflow/WorkflowResource.java

-    @Consumes({MediaType.APPLICATION_JSON})
+    @Produces({MediaType.APPLICATION_JSON})
+    @Consumes(MediaType.APPLICATION_JSON)
    @Operation(operationId = "patchFireMergeSystemAction", summary = "Modify specific fields on multiple contentlets",


You sure this needs to go ?@produces("application/octet-stream")
Becaus I see it return
return Response.ok(new MergeContentletStreamingOutput(contentletsToMergeList, systemAction,
fireActionForm, request, mode, initDataObject))
.header(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON).build();
Which is basically why we had it produce application/octet-stream

Not sure I'm reading correctly. But worth double-checking

You are correct, @fabrizzio-dotCMS; without octet-stream, this endpoint throws a 406 error. I'll fix this on the next commit.

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

Add Swagger annotations to endpoints missing it #32529

Closed

spbolton mentioned this pull request Jul 15, 2025

feat: add Swagger annotations to Batch 3 - Site Architecture & Templates #32658

Closed

spbolton linked an issue Jul 15, 2025 that may be closed by this pull request

Add Swagger annotations to endpoints missing it #32529

Closed

This was referenced Jul 15, 2025

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

Merged

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

Merged

spbolton force-pushed the issue-32529-batch-2 branch from 6947d76 to ce3bed2 Compare July 24, 2025 13:30

spbolton force-pushed the issue-32529-batch-2 branch from ce3bed2 to 645b0d3 Compare August 12, 2025 12:38

spbolton force-pushed the issue-32529-batch-2 branch from b2bf745 to 17d8280 Compare August 27, 2025 11:50

Batch 2 resources

ff46483

spbolton force-pushed the issue-32529-batch-2 branch from 17d8280 to ff46483 Compare August 28, 2025 14:44

github-actions bot added the stale label Sep 28, 2025

github-actions bot closed this Oct 6, 2025

jdcmsd reopened this Dec 9, 2025

jdcmsd added 2 commits December 12, 2025 13:34

Merged origin/main, resolved conflicts, ran test scripts, reviewed in…

8440e45

… app.

snipping application/javascript from a Produces annotation

deaabc0

This comment was marked as outdated.

Sign in to view

jdcmsd marked this pull request as ready for review December 12, 2025 19:22

jdcmsd force-pushed the issue-32529-batch-2 branch from 3ed2b6c to 2423045 Compare December 16, 2025 17:24

jdcmsd added 5 commits December 16, 2025 14:01

Used git rebase --rebase-merges origin/main.

dfc3653

Added example req bodies for _search and v1/content/search

c3cbc99

Fix annotation issues: 1 missing @consumes, 1 duplicate id

0dc7787

Forgot to rebuild before last push

a0b7bfb

tag resource 200 response

ecb310d

jdcmsd force-pushed the issue-32529-batch-2 branch from 997199b to ecb310d Compare December 16, 2025 19:33

spbolton removed the stale label Dec 17, 2025

remove duplicated code from merge

e0da523

extra doc & schema for search, wrapper for _search,

f77c5ba

nollymar requested review from dario-daza and fabrizzio-dotCMS December 18, 2025 22:47

nollymar reviewed Dec 19, 2025

View reviewed changes

dario-daza approved these changes Dec 19, 2025

View reviewed changes

fabrizzio-dotCMS reviewed Dec 19, 2025

View reviewed changes

feat(swagger): Add Swagger annotations to Batch 2 - Content Management Core #32657

Are you sure you want to change the base?

feat(swagger): Add Swagger annotations to Batch 2 - Content Management Core #32657

Uh oh!

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 2: Content Management Core (14 classes)

Content Resources (6 classes)

Content Type Resources (4 classes)

Workflow Resources (1 class)

Categories & Tags (2 classes)

Legacy Content Resources (1 class)

Testing

Impact

Dependencies

Uh oh!

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

Uh oh!

github-actions bot commented Sep 28, 2025

Uh oh!

github-actions bot commented Oct 6, 2025

Uh oh!

This comment was marked as outdated.

jdcmsd commented Dec 16, 2025

Uh oh!

spbolton commented Dec 17, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jdcmsd Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fabrizzio-dotCMS left a comment

Choose a reason for hiding this comment

Uh oh!

fabrizzio-dotCMS Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jdcmsd Dec 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jdcmsd Dec 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

spbolton commented Jul 15, 2025 •

edited

Loading

jdcmsd Dec 19, 2025 •

edited

Loading

fabrizzio-dotCMS Dec 19, 2025 •

edited

Loading

jdcmsd Dec 22, 2025 •

edited

Loading

jdcmsd Dec 22, 2025 •

edited

Loading