Improve documentation for Content Analytics domain-driven query endpoints

[jcastro-dotcms]

Description

As part of the domain-driven Content Analytics REST API redesign (#36628), the new resource-oriented query endpoint(s) (resource + dimensions + metrics + filters model) are now exposed to customers, who will build their own tooling and integrations around them. The current documentation level is insufficient for that audience.

We need to significantly improve the Javadoc and Swagger/OpenAPI documentation for these new endpoints so that external developers can self-serve: understand the query contract, and — most importantly — discover which metrics and dimensions are available and how to combine them to extract specific Content Analytics information, without needing direct support from the dotCMS team.

This is a documentation-only task — no endpoint behavior changes are in scope.

Acceptance Criteria

• Javadoc added/expanded on the new query resource class(es) and their methods, explaining the resource + dimensions + metrics + filters query model
• @Operation / @Parameter / @Schema annotations updated with clear, complete descriptions for every endpoint, parameter, and response field (per REST API Guide — descriptions live in Java annotations, not hand-edited into openapi.yaml)
• At least one realistic request/response @ExampleObject (or equivalent) added per endpoint, showing a representative query
• Documentation enumerates the available metrics (e.g. total events, unique visitors, engagement, etc.) and dimensions (e.g. device, browser, country, content, time) supported by the query model, with a short description of each
• At least 2-3 worked examples showing how to combine specific metrics + dimensions + filters to answer common questions (e.g. "pageviews by device and browser", "clicks by country"), demonstrating the flexibility gained over the old fixed-shape endpoints
• OpenAPI spec verified by starting the app (mvn spring-boot:run) and confirming GET http://localhost:8082/v3/api-docs and /swagger-ui.html render the updated descriptions, parameters, and examples for all three query resources (/v1/events, /v1/sessions, /v1/content) — CAEM has no static openapi.yaml committed; springdoc (springdoc-openapi-starter-webmvc-ui) generates the spec at runtime, so there's nothing to regenerate or commit
• Documentation reviewed for accuracy against the actual implemented query capabilities (no documented metric/dimension that isn't actually supported, and vice versa)
• Create a .md file with human-readable information and code examples that the Documentation Team can use to create and/or improve our official developer documentation

Priority

High

Additional Context

• Parent Epic: Implement domain-driven query REST API for Analytics Dashboard #36628 — Implement domain-driven query REST API for Analytics Dashboard
• Audience: external/customer developers building tooling against the Content Analytics API — documentation should be self-sufficient, not assume internal context
• Scope is limited to Javadoc + Swagger/OpenAPI (@Operation/@Parameter/@Schema annotations); no public docs-site content is in scope here