docs(api): enhance api descriptions for AI Agents

[rjvelazco]

WIP

This PR fixes: #35381

[claude]

Claude finished @rjvelazco's task in 3m 13s —— View job

---

PR Review

• Read changed files and diff
• Analyze Java REST resource changes
• Analyze openapi.yaml changes
• Post review findings

---

Issues to address

1. languageId behavioral claim is unverified — NavResource.java:119-123

The new description states:

"Note: folder names are language-neutral in dotCMS and are not translated — this parameter only affects the 'languageId' attribute on each node, not the visible 'title'."

If this is accurate (i.e., languageId truly has no effect on translated page/folder titles in the nav tree), it describes a significant limitation that users will find counterintuitive and may interpret as a bug. Please confirm this is the actual runtime behavior, and if so, add a note about what the parameter is intended for (e.g., client-side language context, downstream rendering hints), otherwise remove the claim.

2. Known issue documented without a ticket reference — WorkflowResource.java:2959

"⚠️ **Known issue:** Firing `PUBLISH` on an archived contentlet (`archived: true`) does not validate " +
"the archived state and can produce an inconsistent `live: true, archived: true` tri-state."

Documenting a known bug in API docs without a tracker reference creates a maintenance liability: if the bug is fixed, this warning stays forever and confuses users who don't hit it. Add a link to the issue tracker ticket, or at minimum // TODO: remove warning when <issue-id> is resolved in the code. Fix this →

3. @ExampleObject missing name attribute — TempFileResource.java:114, 328

examples = @ExampleObject(
    value = "{ ... }"
)

The OpenAPI spec requires examples within an examples map to have a key/name. Without a name, some spec validators and code generators emit warnings or mishandle the example. Add name = "default" (or something descriptive like "upload-response") to each @ExampleObject. Fix this →

4. deleteContentType quirk should be fixed, not just documented — ContentTypeResource.java:1023-1025

"⚠️ **Note:** The `entity` field in the response is a **JSON-encoded string**, not an object. " +
"Typed clients must call `JSON.parse(entity)` before use..."

This documents a real response inconsistency (double-serialized JSON). Documenting workarounds for bugs is a last resort; the correct fix is to serialize entity as an object like every other endpoint in this family. If the fix is intentionally deferred, there should be a tracked issue. Otherwise, strongly consider fixing this in the same PR to avoid the inconsistency being baked in permanently.

5. depth / languageId YAML type change is a breaking schema change — openapi.yaml:11596-11611

The YAML changes both parameters from type: string to type: integer. The Java method parameters remain String depth and String languageId. Runtime behavior is unchanged (HTTP query params are always strings), but generated API clients from the old spec that used string types will now generate code expecting integer types. This is the right long-term fix but worth acknowledging as a schema-level breaking change for any consumer generating client code from the YAML.

---

Minor notes

• The openapi.yaml is auto-generated by swagger-maven-plugin at compile time (output to WEB-INF/openapi/). Updating both the Java annotations and the YAML in the same PR is correct, but CI should verify the committed YAML matches what the plugin produces — otherwise the YAML drifts between builds.
• The "d61a59e1-a49c-46f2-a929-db2b4bfa88b2" System Workflow UUID is hardcoded as a documentation example. This UUID is installation-seeded so it should be stable, but a note that it's a default-install value would help users on non-standard setups.
• In ContentTypeResource.java:655, the description notes /api/v1/contenttype/{typeId}/fields/** is deprecated. The YAML already marks those endpoints with deprecated: true and "(deprecated)" in their summaries, so this is consistent.