feat(gateway): typed DTO contract for HTTP responses and OpenAPI schema

[bburda]

Pull Request

Summary

The gateway's HTTP payloads were maintained as three independent, hand-written representations - the handler's JSON construction, the OpenAPI schema factories, and the XMedkit extension builder - with nothing keeping them in sync. They drifted: entity list responses advertised a minimal schema while the gateway actually emitted rich x-medkit metadata, so generated clients could not see those fields.

This introduces a typed DTO contract. Each payload is a plain C++17 struct described once by a constexpr field list. Three visitors fold over that single description:

• JsonWriter - struct to wire JSON
• SchemaWriter - type to OpenAPI schema
• JsonReader - request body to struct, with validation

Wire output and OpenAPI schema are therefore generated from one source and cannot drift. All HTTP handler domains (entities, faults, operations, configurations, data, locks, triggers, cyclic-subscriptions, bulk-data, logs, scripts, updates, auth, health) were migrated to the contract, and components/schemas is now generated from the DTO registry. The legacy XMedkit fluent builder and the ~50 hand-written schema factories were removed.

Client-observable changes

• The OpenAPI components/schemas is regenerated from the DTOs; several schema names changed (for example the entity list/detail schemas). Clients generated from the previous spec need to be regenerated.
• Entity responses now always include the type discriminator (previously absent on list items).
• Optional fields previously emitted as empty strings or empty arrays are now omitted when empty. A few fields previously emitted as an explicit null when absent (the script execution progress / started_at / completed_at / parameters / error, and the script parameters_schema) are likewise now omitted; treat an absent key the same as null.
• Request-body validation failures on some PUT/POST endpoints now return the error code invalid-request (HTTP status 400 is unchanged).
• Synchronous operation-execution failures (when the underlying ROS 2 service call fails) now return the standard SOVD GenericError envelope (error_code / vendor_code / parameters) instead of the previous bespoke nested {"error": {"code", "message", "details"}} object (HTTP 500 unchanged).
• Aggregated list endpoints (data, operations, configurations, logs) now re-serialize peer items through the local DTO: peer items that fail validation are dropped and recorded in x-medkit.peer_dropped_items, and peer-supplied fields outside the local schema are no longer preserved verbatim.
• GET /{entity}/data now publishes the opaque DataListResult schema (like GET /{entity}/faults) instead of a typed Collection<DataItem>. The wire payload is unchanged for runtime (ROS 2) entities; for plugin-owned entities, vendor per-item fields (for example the OPC-UA plugin's value / unit / data_type / writable) are now returned verbatim, whereas the previous typed re-parse silently dropped any field outside id / name / category. Clients that generated a typed DataItem model for this route should treat the list response as a free-form object.

Known limitation

The config/log list endpoints emit a richer collection-level x-medkit than the generic Collection<T> wrapper schema types it as. The wire payload stays a valid instance of the published schema; this is a schema-precision gap, documented in design/dto_contract.rst.

---

Issue

Part of #338.

This PR makes the gateway spec accurate. #338 stays open until generated clients are regenerated against the corrected spec and downstream consumers updated, which is follow-up work in separate repositories.

---

Type

• Bug fix
• New feature or tests
• Breaking change
• Documentation only

---

Testing

• New test_dto_contract unit suite round-trips every registered DTO through all three visitors and validates each generated schema.
• Integration tests extended: live endpoint responses are validated against the served OpenAPI spec, and the typed x-medkit sub-schemas are asserted present in the spec.
• Full ros2_medkit_gateway and ros2_medkit_integration_tests suites pass (unit, integration, linters); clang-tidy is clean.

Reviewers can verify by building ros2_medkit_gateway, running colcon test, and hitting GET /api/v1/docs to confirm components/schemas contains the typed entity and x-medkit schemas.

---

Checklist

• Breaking changes are clearly described (and announced in docs / changelog if needed)
• Tests were added or updated if needed
• Docs were updated if behavior or public API changed

[Copilot]

Pull request overview

Introduces a typed DTO contract for the gateway's HTTP responses so that wire JSON, OpenAPI schemas, and x-medkit extensions are all generated from a single C++17 source-of-truth, eliminating drift between handler output and the published spec. All HTTP handler domains were migrated, the legacy XMedkit fluent builder and ~50 hand-written schema factories were removed, and integration tests now validate live responses against the served spec.

Changes:

• Add Draft202012/Draft7 jsonschema validator import with Humble fallback and new skip patterns in test_openapi_callability.test.py for schema limitations (Configuration/Trigger/CyclicSubscription).
• Add new integration test methods to assert typed x-medkit sub-schemas (XMedkitArea, XMedkitRos2, AreaListItem) are present and that live entity GET responses conform to the served OpenAPI spec (with $ref-inlining helper).
• Delete test_x_medkit.cpp since the XMedkit fluent builder is replaced by the DTO/visitor contract.

Reviewed changes

Copilot reviewed 70 out of 70 changed files in this pull request and generated no comments.

File	Description
src/ros2_medkit_integration_tests/test/features/test_openapi_callability.test.py	Adds DTO/schema presence checks, live-response-vs-spec conformance test, and skip patterns for known schema-precision gaps.
src/ros2_medkit_gateway/test/test_x_medkit.cpp	Removed; superseded by the new DTO contract test suite (test_dto_contract).

Note: the PR description states the change touches all handler domains, OpenAPI builder, and removes ~50 schema factories, but only two files are visible in this diff slice. The bulk of the migration (handlers, DTO/visitor framework, OpenAPI builder rewiring, test_dto_contract) is outside the reviewed hunks and cannot be assessed here.