docs(gateway): correct schema-generation description (opaque DTOs, no merged survivors)

The OpenAPI tutorial and the DTO contract design doc overstated the
field-walking path:

- components/schemas is now exactly collect_component_schemas(); the
  from_ros_msg / *_srv_* / binary_schema / generic_object_schema factories are
  no longer merged into it. They feed inline path-operation schemas for the
  per-topic / per-service / per-action routes whose shape comes from the live
  ROS 2 type, not from a named DTO.
- The Data*Result / Fault*Result / OperationExecutionResult opaque DTOs have no
  dto_fields; they carry a hand-written JsonWriter/JsonReader/SchemaWriter trio
  and publish an opaque object schema (type: object, additionalProperties: true,
  x-medkit-opaque: true) rather than a field-walked struct or a bare {}.

Author: bburda

docs/tutorials/openapi.rst

@@ -81,20 +81,29 @@ How Schemas Are Generated
 --------------------------
 
 The ``components/schemas`` object in every ``/docs`` response is generated
-automatically from the DTO registry. Each response and request type in the
-gateway is declared as a plain C++ struct with a ``constexpr dto_fields<T>``
-descriptor tuple. The ``SchemaWriter<T>`` visitor folds over this tuple at
-compile time to produce the OpenAPI JSON Schema entry, and the
-``AllDtos`` registry in ``dto/registry.hpp`` lists every named type so that
-``collect_component_schemas()`` can populate the full schema map without
-any hand-written schema factories.
-
-The same descriptor is used for serialization (``JsonWriter<T>``) and
-request-body validation (``JsonReader<T>``), so the wire shape and the
-published schema are always derived from the same source. Genuinely dynamic
-payloads - such as live ROS 2 message data and free-form fault environment
-records - are typed as ``nlohmann::json`` members and appear in the schema
-as unconstrained objects (``{}``).
+automatically from the DTO registry. Most response and request types are
+declared as a plain C++ struct with a ``constexpr dto_fields<T>`` descriptor
+tuple; the ``SchemaWriter<T>`` visitor folds over this tuple at compile time to
+produce the OpenAPI JSON Schema entry. The ``AllDtos`` registry in
+``dto/registry.hpp`` lists every named type so that
+``collect_component_schemas()`` populates the entire ``components/schemas`` map
+with no hand-written schema factories.
+
+For a field-walking DTO the same descriptor also drives serialization
+(``JsonWriter<T>``) and request-body validation (``JsonReader<T>``), so the wire
+shape and the published schema are always derived from the same source.
+
+A few envelope types whose payload shape is decided at runtime by a plugin or by
+a live ROS 2 type - the ``Data*Result`` / ``Fault*Result`` /
+``OperationExecutionResult`` *opaque* DTOs - have no ``dto_fields``. They carry a
+hand-written ``JsonWriter`` / ``JsonReader`` / ``SchemaWriter`` trio instead, are
+still listed in ``AllDtos``, and publish an opaque object schema
+(``{type: object, additionalProperties: true, x-medkit-opaque: true}``). Inside
+an ordinary DTO, a free-form member typed as a bare ``nlohmann::json`` (for
+example the fault environment records) appears as an unconstrained object
+(``{}``). The per-topic / per-service / per-action routes for live ROS 2 data do
+not use ``components/schemas`` at all: their request and response bodies carry an
+inline schema derived from the ROS 2 type on the route itself.
 
 For the full design of the DTO contract layer, see
 :doc:`/design/ros2_medkit_gateway/dto_contract`.

src/ros2_medkit_gateway/design/dto_contract.rst

@@ -268,20 +268,19 @@ AllDtos Registry (``registry.hpp``)
 
 The free function ``collect_component_schemas()`` iterates ``AllDtos`` at
 compile time (via ``std::index_sequence``) and calls
-``SchemaWriter<T>::schema()`` for each type, producing the bulk of the
-``components/schemas`` map. ``SchemaBuilder::component_schemas()`` (in
-``src/openapi/schema_builder.cpp``) merges these DTO-generated entries with a
-small number of explicitly hand-written survivors:
-
-- **``from_ros_msg`` / ``from_ros_srv_request`` / ``from_ros_srv_response``** -
-  schema factories for dynamic ROS 2 payloads whose field names are not known
-  at compile time (topic samples, service request/response bodies).
-- **``binary_schema``** and **``generic_object_schema``** - trivial inline
-  schema objects used for bulk-data and free-form fields.
-
-With the exception of these survivors, every schema in ``components/schemas``
-is generated from ``AllDtos``. No runtime loop over a dynamic registry is
-required.
+``SchemaWriter<T>::schema()`` for each type. ``SchemaBuilder::component_schemas()``
+(in ``src/openapi/schema_builder.cpp``) returns exactly this map: every entry in
+``components/schemas`` is generated from ``AllDtos``, with no hand-written
+survivors merged in. No runtime loop over a dynamic registry is required.
+
+The hand-written schema factories that remain on ``SchemaBuilder`` -
+``from_ros_msg`` / ``from_ros_srv_request`` / ``from_ros_srv_response`` (for
+dynamic ROS 2 payloads whose field names are not known at compile time) and
+``binary_schema`` / ``generic_object_schema`` - are no longer part of the
+``components/schemas`` map. They are called by the path builder
+(``src/openapi/path_builder.cpp``) to emit *inline* operation schemas for the
+per-topic / per-service / per-action routes, whose request and response shape is
+derived from the live ROS 2 type rather than from a named DTO.
 
 The ``Collection<T>`` template is a generic DTO for paginated list responses
 (``{"items": [...]}``). It is specialized for each element type in
@@ -539,23 +538,25 @@ OpenAPI Generation Pipeline
 
 The published ``openapi.json`` is assembled mechanically from two sources:
 
-- ``components/schemas`` is the union of
-  ``collect_component_schemas<AllDtos>()`` (one entry per DTO listed in
-  ``dto/registry.hpp``) and a small set of explicit survivors in
-  ``SchemaBuilder::component_schemas()`` for genuinely dynamic ROS payloads
-  (``from_ros_msg`` / ``from_ros_srv_request`` / ``from_ros_srv_response``,
-  ``binary_schema``, ``generic_object_schema``).
+- ``components/schemas`` is exactly ``collect_component_schemas<AllDtos>()`` -
+  one entry per DTO listed in ``dto/registry.hpp``, with no hand-written
+  survivors merged in.
 - ``paths`` is ``RouteRegistry::to_openapi_paths()``: every typed route
   contributes a path item with ``$ref`` entries auto-derived from its
   ``TResponse`` / ``TBody`` template parameters plus any tags, summary,
   description, ``operation_id``, parameter, or extra-status metadata pinned
-  on the route via the fluent ``RouteEntry`` builder.
+  on the route via the fluent ``RouteEntry`` builder. The per-topic /
+  per-service / per-action routes for genuinely dynamic ROS 2 payloads carry an
+  *inline* schema built by ``SchemaBuilder``'s ``from_ros_msg`` /
+  ``from_ros_srv_request`` / ``from_ros_srv_response`` / ``binary_schema`` /
+  ``generic_object_schema`` factories (these feed path operations, not
+  ``components/schemas``).
 
 ``OpenApiSpecBuilder::build()`` then assembles ``info`` / ``servers`` /
 ``tags`` / ``security`` around those two compiled blocks. There are no
-hand-written ``paths`` items in the published spec, and no hand-written
-schema blocks beyond the survivors above. Adding a route or a DTO field
-updates the spec on the next process start with no schema-side edit.
+hand-written ``paths`` items in the published spec, and no hand-written schema
+blocks in ``components/schemas``. Adding a route or a DTO field updates the
+spec on the next process start with no schema-side edit.
 
 Optional fields are now emitted as ``anyOf: [<inner>, {type: "null"}]``
 (OpenAPI 3.1 idiom) so generated clients see ``T | null`` rather than