fix: Container REST API — hostId ignored, containerStructures broken, and missing @Schema annotations

The Container REST API (/api/v1/containers) has three bugs discovered during AI agent integration testing via the OpenAPI spec:

Bug 1: hostId field is accepted but silently ignored

• ContainerForm accepts hostId and the OpenAPI spec advertises it
• But ContainerResource.saveNew() (line 779) and update() (line 874) never read containerForm.getHostId()
• Both endpoints get the host from WebAPILocator.getHostWebAPI().getCurrentHostNoThrow(request) instead
• The _copy endpoint has the same issue (line 1424)
• Result: site assignment cannot be controlled via the API — containers always land on the current request's site

Bug 2: containerStructures causes Hibernate session error on POST and PUT

• Sending containerStructures array in the request body causes HTTP 400 with a Hibernate error
• Root cause: The Hibernate mapping (DotCMSId.hbm.xml:457) uses unsaved-value="" on the id field — if the client sends an id value, Hibernate tries an UPDATE on a non-existent row instead of INSERT
• The saveContainerStructures() method (ContainerAPIImpl.java:551) calls HibernateUtil.save() with these detached/misidentified objects
• Workaround: use top-level structureInode + code fields instead

Bug 3: ContainerForm has no @Schema annotations

• None of the fields on ContainerForm or its Builder have @Schema annotations
• The OpenAPI spec auto-generates with no descriptions, making it unclear that friendlyName is the "description" field
• Fields like hostId and containerStructures appear usable in the spec but are broken/ignored

Affected files

• dotCMS/src/main/java/com/dotcms/rest/api/v1/container/ContainerResource.java
• dotCMS/src/main/java/com/dotcms/rest/api/v1/container/ContainerForm.java
• dotCMS/src/main/java/com/dotmarketing/portlets/containers/business/ContainerAPIImpl.java
• dotCMS/src/main/java/com/dotmarketing/beans/ContainerStructure.java
• dotCMS/src/main/resources/com/dotmarketing/beans/DotCMSId.hbm.xml
• dotCMS/src/main/webapp/WEB-INF/openapi/openapi.yaml

Acceptance Criteria

• POST/PUT /api/v1/containers uses hostId from the request body (when provided) to determine the container's site, falling back to the current request site if not set
• POST/PUT /api/v1/containers correctly saves containerStructures sent in the request body without Hibernate errors
• ContainerForm fields have @Schema annotations with descriptions (especially friendlyName documented as "description", and hostId documented with its behavior)
• The generated OpenAPI spec accurately reflects which fields are functional
• Existing container creation/update flows (UI, integrations) continue to work

Root Cause Summary

Priority

Medium