docs: add OpenAPI annotations to 18 MCP-priority REST resources

[fmontes]

Summary

• Adds @Operation, @ApiResponses, @Parameter, and @RequestBody annotations to ~100 previously undocumented endpoints across 14 REST resource files
• Raises MCP-priority OpenAPI documentation coverage from 41% to near 100%
• Fixes 4 critical schema bugs that caused ~40% of MCP API call failures
• Replaces all generic ResponseEntityView.class and Object.class schemas with specific typed view classes across all MCP-priority resources

Key Fixes

Issue	Fix
ES search body schema wrong	@RequestBody with proper schema on POST; GET variants marked @Hidden
cacheTTL type mismatch	Documented as string (not int) in page endpoint descriptions
sortOrder missing	Noted as required in page endpoint descriptions
FormDataMultiPart leaking	Replaced with descriptive @Schema(type="object") in workflow/temp endpoints
Contentlet field opaque	Listed required fields (contentType, title, languageId) in fire endpoints
SYSTEM_FOLDER restriction	Documented in page and workflow fire endpoints
siteId/hostId/host aliases	Noted in site endpoint parameter descriptions
theme/themeId aliases	Noted in template/theme endpoint descriptions
v1 Tags undocumented	All 10 methods annotated and marked deprecated, referencing v2
Generic ResponseEntityView.class schemas	Replaced 35 instances with specific typed view classes (e.g., ResponseEntityPageView, ResponseEntitySiteView, ResponseEntityMapStringObjectView)
Generic Object.class schemas	Replaced with specific view classes or type="object" with meaningful descriptions for unwrapped returns

Schema Improvements (35 generic schemas replaced)

File	Schemas Fixed	Specific View Classes Used
PageResource	10	EmptyPageView, PageView, ContentView, ContentletMapsView, TemplateView, PageLivePreviewVersionView, MulitreeView, ListPersonalizationPersonaPageView, PaginatedDataView, LanguagesForPageView
SiteResource	6	SiteView, ListMapView, SiteSwitchView, SiteSetupProgressView
WorkflowResource	9	MapStringObjectView (all fireAction methods)
TemplateResource	2	ListTemplateView, type="object" with description
ContentResource	1	SearchView
LanguagesResource	2	type="object" for unwrapped map, MapStringStringView
ThemeResource	2	PaginatedArrayListMapView, MapStringObjectView
TempFileResource	2	type="object" with meaningful descriptions
TagResource (v1)	1	type="object" for unwrapped map

Metrics

Metric	Before	After
Operations with summary	244	341 (+97)
Auto-generated operationIds	~130	113
Critical schema bugs	4	0
Generic ResponseEntityView.class in MCP resources	24	0
Generic Object.class in MCP resources	18	0 (replaced with specific views or typed descriptions)

Files Changed (16)

14 Java REST resources + 1 new view class + regenerated openapi.yaml

• ESContentResourcePortlet.java — 4 methods
• ContentResource.java — 11 methods + 1 schema fix
• NavResource.java — 1 method
• PageResource.java — 14 methods + 10 schema fixes
• SiteResource.java — 18 methods + 6 schema fixes
• TemplateResource.java — 14 methods + 2 schema fixes
• WorkflowResource.java — schema fixes on ~8 methods + 9 schema fixes
• CategoriesResource.java — 9 methods
• FolderResource.java — 7 methods
• ContainerResource.java — 21 methods
• TagResource.java (v1) — 10 methods (all deprecated) + 1 schema fix
• LanguagesResource.java — 2 methods + 2 schema fixes
• ThemeResource.java — 2 methods + 2 schema fixes
• TempFileResource.java — 2 methods + 2 schema fixes
• ResponseEntityHostView.java — new view class
• openapi.yaml — regenerated

Test plan

• Build compiles successfully (./mvnw install -pl :dotcms-core -DskipTests)
• OpenAPI YAML regenerates without errors
• No business logic was modified — annotation-only changes
• Verify schema types match actual method return types
• Spot-check Swagger UI renders endpoints correctly

🤖 Generated with Claude Code

[github-actions]

❌ Issue Linking Required

This PR could not be linked to an issue. All PRs must be linked to an issue for tracking purposes.

How to fix this:

Option 1: Add keyword to PR body (Recommended - auto-removes this comment)
Edit this PR description and add one of these lines:

• This PR fixes #123 or Fixes: #123

• This PR closes #123 or Closes: #123

• This PR resolves #123 or Resolves: #123

• Other supported keywords: fix, fixed, close, closed, resolve, resolved
  Option 2: Link via GitHub UI (Note: won't clear the failed check)

1. Go to the PR → Development section (right sidebar)

2. Click "Link issue" and select an existing issue

3. Push a new commit or re-run the workflow to clear the failed check
   Option 3: Use branch naming
   Create a new branch with one of these patterns:

• 123-feature-description (number at start)

• issue-123-feature-description (issue-number at start)

• feature-issue-123 (issue-number anywhere)

Why is this required?

Issue linking ensures proper tracking, documentation, and helps maintain project history. It connects your code changes to the problem they solve.---

This comment was automatically generated by the issue linking workflow

[semgrep-code-dotcms-test]

Semgrep found 1 tainted-file-path finding:

• dotCMS/src/main/java/com/dotcms/rest/ContentResource.java
  • L2001-2002 - 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/b1e8a1a7375a407ae4b8ff3647881ddac3100ed1/dotCMS/src/main/java/com/dotcms/rest/ContentResource.java#L1794 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1794] multipart</a>"]
        end
        %% Intermediate

        subgraph Traces0[Traces]
            direction TB

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

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

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

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

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

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

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

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

            v10["<a href=https://github.com/dotCMS/core/blob/b1e8a1a7375a407ae4b8ff3647881ddac3100ed1/dotCMS/src/main/java/com/dotcms/rest/ContentResource.java#L1987 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1987] 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/b1e8a1a7375a407ae4b8ff3647881ddac3100ed1/dotCMS/src/main/java/com/dotcms/rest/ContentResource.java#L2001 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 2001] 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

Loading

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

[semgrep-code-dotcms-test]

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

• dotCMS/src/main/java/com/dotcms/rest/ContentResource.java
  • L2002 - 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/66e70a909e64d1f2f33451a633872dc8288a697c/dotCMS/src/main/java/com/dotcms/rest/ContentResource.java#L1794 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1794] multipart</a>"]
        end
        %% Intermediate

        subgraph Traces0[Traces]
            direction TB

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

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

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

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

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

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

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

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

            v10["<a href=https://github.com/dotCMS/core/blob/66e70a909e64d1f2f33451a633872dc8288a697c/dotCMS/src/main/java/com/dotcms/rest/ContentResource.java#L1987 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 1987] 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/66e70a909e64d1f2f33451a633872dc8288a697c/dotCMS/src/main/java/com/dotcms/rest/ContentResource.java#L2002 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 2002] tmpFolder.getAbsolutePath() + File.separator + filename</a>"]
        end
    end
    %% Class Assignment
    Source:::invis
    Sink:::invis

    Traces0:::invis
    File0:::invis

    %% Connections

    Source --> Traces0
    Traces0 --> Sink

Loading

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

[fmontes]

@claude code review this.

[claude]

Claude finished @fmontes's task —— View job

---

Code Review: OpenAPI Annotations PR

Review Progress:

• Analyze PR scope and changes
• Review key OpenAPI annotation implementations
• Check security findings
• Assess reviewer feedback on view classes
• Provide comprehensive feedback

---

🎯 Overall Assessment: Strong Implementation with Critical Security Issue

This PR significantly improves dotCMS's OpenAPI documentation coverage and follows most established patterns correctly. However, there's one critical security vulnerability that must be addressed before merge.

🚨 Critical Issue: Path Traversal Vulnerability

PRIORITY: MUST FIX BEFORE MERGE

Location: ContentResource.java:2001-2002

final File tempFile = new File(
    tmpFolder.getAbsolutePath() + File.separator + filename);

Problem: While the code sanitizes the filename on line 1987 using FileUtil.sanitizeFileName(badFileName), Semgrep is flagging this as a path traversal vulnerability. The security concern is valid - even sanitized filenames could potentially contain directory traversal sequences.

Fix: Use Paths.get() and resolve() for safer path construction:

final File tempFile = tmpFolder.toPath()
    .resolve(Paths.get(filename).getFileName()) // Only use filename component
    .toFile();

This ensures only the filename portion is used, preventing any potential directory traversal.

✅ Strong Points

1. Excellent Schema Pattern Compliance

The PR correctly follows dotCMS's schema implementation rules:

• Uses specific ResponseEntity*View classes instead of generic ResponseEntityView.class
• Properly matches schemas to actual method return types
• Creates new view classes where needed (e.g., ResponseEntityHostView)

2. Comprehensive Annotation Coverage

• Adds @Operation, @ApiResponses, @Parameter, and @RequestBody to ~100 endpoints
• Consistent parameter descriptions with examples
• Proper response code documentation (200, 400, 401, 403, 404)

3. Consistent Patterns

• All @Produces annotations at method level ✅
• Proper @Consumes usage (only on POST/PUT with bodies) ✅
• Standardized media types (MediaType.APPLICATION_JSON) ✅

🔧 Recommended Improvements

1. Use More Specific View Classes (per @jdcmsd's feedback)

Several instances could use more specific view classes that already exist:

CategoriesResource.java:

• Replace ResponseEntityCategoryView with more specific classes:
  • For methods returning child count: ResponseEntityCategoryWithChildCountView
  • For simple category operations: ResponseEntityCategoryView (already correct)

ContainerResource.java:

• Lines with @Schema(implementation = Object.class) should use:
  • ResponseEntityContainerObjectMapView for Map<String, Object> returns
  • ResponseEntityContainerWithContentTypesView for container + content types

FolderResource.java:

• Delete operations: Check if they return just the folder (ResponseEntityFolderView) or include subfolders (ResponseEntityFolderWithSubfoldersView)

2. Minor Documentation Enhancements

Parameter Descriptions: Some could be more specific:

// Current
@Parameter(description = "Language ID for the page content")

// Better 
@Parameter(description = "Language ID for the page content (e.g., 1 for English, 2 for Spanish)")

3. Consistent Response Descriptions

Some methods use generic descriptions like "Success" - consider more specific descriptions like:

• "Page metadata retrieved successfully"
• "Workflow actions returned successfully"

📋 Schema Pattern Validation

The PR correctly implements dotCMS schema patterns:

✅ Pattern 1 - Wrapped Responses: Uses specific ResponseEntity*View classes
✅ Pattern 2 - Unwrapped Collections: Uses Object.class appropriately
✅ Pattern 3 - Generic Utilities: Uses ResponseEntityMapView, ResponseEntityStringView etc.
❌ Anti-pattern: No instances of banned ResponseEntityView.class found ✅

🔗 Missing Issue Link

The PR needs to be linked to a GitHub issue as flagged by the automation. Add one of these to the description:

• Fixes #[issue-number]
• Closes #[issue-number]
• Resolves #[issue-number]

📊 Impact Assessment

• API Coverage: ↑ From 41% to near 100% for MCP-priority resources
• Schema Quality: ↑ Eliminates 35+ generic schemas with specific types
• Security: ⚠️ One critical vulnerability needs fixing
• Documentation: ↑ Significantly improves API discoverability

🎯 Action Items

Before Merge:

1. 🚨 CRITICAL: Fix path traversal vulnerability in ContentResource.java
2. 📎 REQUIRED: Link to GitHub issue
3. ✨ RECOMMENDED: Consider more specific view classes per reviewer feedback

Post-Merge:

• Regenerate OpenAPI documentation
• Update MCP integration tests if needed

---

Verdict: Excellent OpenAPI implementation work that significantly improves documentation coverage, but requires security fix before merge.

[jdcmsd]

It can probably merge as is, though the @consumes and @RequestBody stuff will need attention in a future adjustment. (See attached conversation)

[spbolton]

@freddy I did already have updates to fix and also enforce through test that all the endpoints were correct and had everything we need. I went through and broke this up to 9 PRs but was not prioritised as I transitioned into platform after getting Batch 1 in the system. There is probably some duplication of work here and the changes may make it even more difficult to sync up merge conflicts. We should see if there is anything we can salvage from the work I have already done, and I think the work I have to have ongoing tests to prevent new changes to the rest endpoints from missing the correct annotations is still useful.

We got held up on Batch 2 because it raised some questions on how we were handling file streaming consistently. I just did not have any cycles to go back in and support Jamie on this

#32657

#32529 (comment)

Do we throw away these PRs. Do we try to add the validation logic from this PR more focused on the important APIs but work with the changes here.