Derive the OpenAPI document from the code instead of declaring it alongside

[bburda]

Pull Request

Summary

The generated OpenAPI document asserted a great deal the gateway does not honour, and omitted a great deal it does. The common cause was that facts about a route were declared separately from the handler implementing them, so the two drifted with nothing checking.

This derives what can be derived, and where it cannot be derived, declares it once at a seam that also does the work.

The governing rule, now stated in design/openapi_derivation.rst: if a fact about a route can be derived from the handler, it must not be declared separately; where it cannot, the declaration lives at a seam that also does the work.

What now derives itself

• The success status comes from the handler's return type (Created<T>, Accepted<T>, status_payload_t) rather than a hand-attached number.
• Feature gates declare the status they return, so a gated route publishes its 501.
• The typed route registry is the single source for paths, parameters, response headers and error sets.
• The RBAC permission table is generated from the route registrations. Enforcement did not move - check_authorization still fails closed where it always did, because docs, Swagger UI and plugin routes are registered outside the registry and would lose their rule.
• The <entity-path>/docs sub-documents are projected from the real document instead of rebuilt by hand.
• Per-operation security is published only where the deployment actually checks it, keyed on the auth policy rather than on auth.enabled.

Measured against a running gateway

	before	after
Operations declaring a 2xx they cannot return	45	0
Routes that answer 501 without declaring it	28	0
Schemas unreachable from any operation	15	0
Operations publishing a body with no content	9	0
format: binary (invalid in OpenAPI 3.1)	12	0
Operations with no description	12	0
Error codes documented	21	44 of 47
Dangling $ref in /docs sub-documents	12	0

Verification probed all 238 documented operations against live gateways in five configurations - feature gates on and off, auth off and all three require_auth_for values, plugin loaded and not - and found no status the gateway emits that the document does not declare.

Defects found and fixed along the way

These were not documentation problems:

• A downstream validation refusal was reported to clients as 503, because the classification matched a substring of the error message. Replaced with a two-state outcome set at the transport's no-response paths, defaulting to the client-error side so a server error must be asked for.
• fault_code was published with a maximum of 256 while the fault manager enforced 128; values in between produced a server error. Bounds reconciled.
• Raising that bound exposed silent data loss: a long fault code pushed the rosbag directory name past NAME_MAX, the exception was caught and only logged, and the bag was never written. The name is now bounded and carries a digest so truncated codes stay distinguishable.
• Any 401/403/429 answered before the request body was read stranded the payload and poisoned the keep-alive connection, so the next request on it received a spurious 400.
• DELETE /{entity}/configurations/{config_id} did not enforce the length bound its siblings enforce and the document published.
• The /docs sub-documents published a request body the handler rejects, and a 200 body the gateway never returns.
• An execution started through an aggregate was listed by that entity but not readable on it. The collection and the item routes now apply one rule: an execution belongs to the entity it was started on, and is also reachable under the member a qualified id names.
• The document published an operation id no caller can reach. A service and an action may share a short name and a ROS path, and neither form of the item half separates them, so both collapsed to one id that answers 400 and the second overwrote the first in the document. An id that names more than one operation now gets no path item; the templated route still describes the request.
• A configuration write published a schema that accepts {}, which the handler answers 400 for. The rule spans two members, so the descriptor could not carry it; it is now stated once next to them.

Enforcement, so this does not come back

• A contract test walking the served document: unique operation identity, resolving $refs, no phantom 2xx, every advertised collection served, every operation described, no role published where none is enforced.
• A build-time status recorder asserting every status the gateway emits is declared.
• A startup completeness check over the shipped route set.
• A checker asserting every error code with a non-test emitter appears in the documented table.
• A checker resolving every test citation in the design docs against the test tree.

---

Issue

• closes [BUG] The generated OpenAPI document asserts what the gateway does not honour #583

---

Type

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

---

Testing

Gateway unit suite and the integration suite, plus contract suites added here: test_openapi_contract, test_openapi_callability, test_openapi_error_coverage, test_openapi_response_drift, test_rbac_contract, test_auth_policy_contract, test_locking_disabled_contract.

Reviewers can reproduce the central claim directly:

curl -s localhost:8080/api/v1/docs | jq -S . > spec.json
# then drive any documented operation and compare the status against its declaration

Re-verified after rebasing onto current main (25 commits had landed since this
work started): gateway builds with zero warnings, 2678 unit tests and
137 contract cases pass, no orphaned processes left behind. The one conflict
was the per-target coverage list, which main replaced with a directory-scope
module that instruments every target automatically.

Two tests are red and are not caused by this branch:

• test_external_app_fault_rollup fails roughly two runs in three on an idle machine. Diagnosed here: RosbagCapture::start() runs from the FaultManagerNode constructor while the node's graph cache is still empty, so nothing is buffered for the first 500 ms and a fault confirmed in that window gets no bag. Written up on [BUG] A fault confirmed right after a post-fault recording window gets no rosbag #574, which is a different entry path into the same sink; left unfixed by owner decision.
• test_opcua_secured launches the fault manager with no parameters, so storage defaults to /var/lib/ros2_medkit, which the test runner cannot create; create_storage() rethrows and the node aborts before its service appears. One launch parameter fixes it; out of scope here.

---

Known limitations

Stated rather than left to be discovered:

• The concrete cache-derived items in <entity-path>/docs carry no payload schema on any gateway: all four TopicData construction sites push an empty type, so the schema-generating branch never runs in production. The items still carry the SOVD extensions and the correct write envelope.
• A plugin GET route whose path ends in /docs is silently unreachable - route registration order puts the docs catch-all first, with no warning at registration.
• The /docs sub-document cache bounds entries rather than bytes; caching the serialized form rather than the parsed tree cut resident growth by about 40% and the per-hit copy by about 70%, but the entry bound is still the wrong unit.
• <entity-path>/docs answers 404 for four collections that are served and advertised (locks, scripts, fault-triggers, status), and 200 with an empty document for two nested paths that are not served.

A tooling gap this surfaced

The plugin packages do not set CMAKE_EXPORT_COMPILE_COMMANDS, so they produce
no compile_commands.json and the pre-push clang-tidy hook cannot resolve the
gateway headers they include - reporting them as missing on files that compile
clean. Nine other packages set it. It bites whoever next touches a file in
ros2_medkit_graph_provider or ros2_medkit_graph_watchdog; both are outside
this change's subject, so it is reported rather than fixed here.

---

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

This PR makes the served OpenAPI 3.1 document a derived artifact of the gateway’s typed route registry and handler signatures, reducing drift between documentation and real runtime behavior. It also adds contract-style tests and a few targeted runtime fixes uncovered while validating the document against live gateways.

Changes:

• Derive per-route success statuses, declared errors, headers, and auth security requirements from typed handler return types and route registrations (including plugin route descriptions where available).
• Normalize/centralize URI construction (notably Location on 201/202 responses) and tighten several request/response correctness edges found during live-spec probing.
• Add/expand unit + integration + contract tests that mechanically enforce OpenAPI/document consistency (status surface, schema reachability, error coverage, RBAC contract, etc.).

Reviewed changes

Copilot reviewed 152 out of 172 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/ros2_medkit_serialization/include/ros2_medkit_serialization/type_cache.hpp	Explicitly deletes move ops; documents lifetime.
src/ros2_medkit_plugins/ros2_medkit_graph_provider/README.md	Clarifies plugin-only links and docs contribution.
src/ros2_medkit_plugins/ros2_medkit_graph_provider/CMakeLists.txt	Enables compile_commands.json export for tooling.
src/ros2_medkit_msgs/README.md	Updates fault_code contract documentation.
src/ros2_medkit_log_bridge/src/log_bridge_node.cpp	Clamping/parameter parsing tweaks; signature polish.
src/ros2_medkit_log_bridge/include/ros2_medkit_log_bridge/log_bridge_node.hpp	Adjusts cooldown_allows signature to const-ref.
src/ros2_medkit_integration_tests/test/scenarios/test_scenario_discovery_manifest.test.py	Pins Area capability advertising of /components.
src/ros2_medkit_integration_tests/test/scenarios/test_scenario_bulk_data_download.test.py	Asserts download media type is explicitly declared.
src/ros2_medkit_integration_tests/test/features/test_updates.test.py	Adds malformed-body vs gate precedence + 501 declaration checks.
src/ros2_medkit_integration_tests/test/features/test_scripts_api.test.py	Pins collection-correct URLs and trailing-slash Location behavior.
src/ros2_medkit_integration_tests/test/features/test_openapi_response_drift.test.py	Adds write-route status drift checks (201/202 + empty body).
src/ros2_medkit_integration_tests/test/features/test_locking.test.py	Verifies 201 Location resolves (incl trailing slash).
src/ros2_medkit_integration_tests/test/features/test_health.test.py	Ensures endpoint list has no duplicates; refines schema checks.
src/ros2_medkit_integration_tests/test/features/test_graph_provider_plugin.test.py	Pins plugin-emitted top-level x-medkit-graph link.
src/ros2_medkit_integration_tests/test/features/test_docs_endpoint.test.py	Ensures nested-entity sub-docs describe nothing (empty paths).
src/ros2_medkit_integration_tests/test/features/test_configuration_api.test.py	Adds config_id bound enforcement + unconvertible value is 400.
src/ros2_medkit_integration_tests/test/features/test_auth.test.py	Exercises per-operation security filtering with plugin route.
src/ros2_medkit_integration_tests/ros2_medkit_test_utils/launch_helpers.py	Adds reusable gateway parameter presets (plugin/full-feature).
src/ros2_medkit_integration_tests/ros2_medkit_test_utils/gateway_test_case.py	Adds assert_declared_media_type helper.
src/ros2_medkit_integration_tests/CMakeLists.txt	Raises timeout for heavy auth-policy contract test.
src/ros2_medkit_gateway/test/test_update_manager.cpp	Adds lifetime tests for shutdown draining async tasks.
src/ros2_medkit_gateway/test/test_trigger_manager.cpp	Pins SSE trigger-event frame schema shape.
src/ros2_medkit_gateway/test/test_sse_transport_provider.cpp	Pins vendor-error sentinel pairing and success/error frame shapes.
src/ros2_medkit_gateway/test/test_script_handlers.cpp	Updates tests for Created/Accepted wrappers and exact Locations.
src/ros2_medkit_gateway/test/test_schema_builder.cpp	Clarifies schema rationale for execution capability field.
src/ros2_medkit_gateway/test/test_route_descriptions.cpp	Adds tests for operation identity + security semantics.
src/ros2_medkit_gateway/test/test_operation_handlers.cpp	Updates for Accepted<> wrapper and Location behavior.
src/ros2_medkit_gateway/test/test_openapi_spec_builder.cpp	Verifies middleware-owned responses are always present.
src/ros2_medkit_gateway/test/test_lock_manager.cpp	Pins extend/release status surface (no 409; includes 403).
src/ros2_medkit_gateway/test/test_lifecycle_handlers.cpp	Updates to Accepted<> wrapper; removes runtime status override.
src/ros2_medkit_gateway/test/test_fault_manager.cpp	Pins typed fault failure classification from transport layer.
src/ros2_medkit_gateway/test/test_fault_handlers.cpp	Pins 404-vs-503 split based on typed failure, not message text.
src/ros2_medkit_gateway/test/test_dto_contract.cpp	Adds vendor_code schema/wire contract; improves schema shape checks.
src/ros2_medkit_gateway/test/test_docs_handlers.cpp	Converts /docs root to typed text response; byte-equality checks.
src/ros2_medkit_gateway/test/test_discovery_models.cpp	Fixes capability key naming to match served routes.
src/ros2_medkit_gateway/test/test_discovery_handlers.cpp	Ensures graph link omitted when plugin not loaded.
src/ros2_medkit_gateway/src/ros2/transports/ros2_parameter_transport.cpp	Maps JSON conversion throws to INVALID_VALUE (400), not 500.
src/ros2_medkit_gateway/src/ros2/transports/ros2_fault_service_transport.cpp	Sets FaultFailure on no-response paths.
src/ros2_medkit_gateway/src/openapi/schema_builder.hpp	Removes OpenAPI 3.0-style binary schema helper.
src/ros2_medkit_gateway/src/openapi/schema_builder.cpp	Removes format: binary schema emission.
src/ros2_medkit_gateway/src/openapi/openapi_spec_builder.hpp	Allows schemes without global document-level requirement.
src/ros2_medkit_gateway/src/http/handlers/update_handlers.cpp	Migrates to Created/Accepted wrappers + Location helper.
src/ros2_medkit_gateway/src/http/handlers/trigger_handlers.cpp	Migrates POST to Created<> + Location normalization.
src/ros2_medkit_gateway/src/http/handlers/sse_transport_provider.cpp	Adds vendor_code to vendor-error SSE frames.
src/ros2_medkit_gateway/src/http/handlers/lock_handlers.cpp	Migrates POST to Created<> + canonicalized child Location.
src/ros2_medkit_gateway/src/http/handlers/lifecycle_handlers.cpp	Uses api_path + Accepted<> for transitions.
src/ros2_medkit_gateway/src/http/handlers/health_handlers.cpp	Includes plugin-mounted endpoints in root endpoint list.
src/ros2_medkit_gateway/src/http/handlers/fault_handlers.cpp	Replaces substring error classification with typed failure flag.
src/ros2_medkit_gateway/src/http/handlers/docs_handlers.cpp	Serves cached pre-serialized JSON text for docs.
src/ros2_medkit_gateway/src/http/handlers/cyclic_subscription_handlers.cpp	Migrates POST to Created<> + child Location.
src/ros2_medkit_gateway/src/http/handlers/config_handlers.cpp	Enforces config_id length bound on DELETE.
src/ros2_medkit_gateway/src/http/handlers/bulkdata_handlers.cpp	Adds finite+wildcard download media type set; Created<> upload.
src/ros2_medkit_gateway/src/gateway_node.cpp	Drains UpdateManager before notifier shutdown to avoid UAF.
src/ros2_medkit_gateway/src/entity_freeze_frame_capture.cpp	Minor callback signature tightening.
src/ros2_medkit_gateway/src/core/openapi/path_resolver.cpp	Documents known live gaps in <entity-path>/docs resolution.
src/ros2_medkit_gateway/src/core/models/entity_types.cpp	Adds resource-collection string mappings (data-groups, triggers, etc.).
src/ros2_medkit_gateway/src/core/managers/update_manager.cpp	Makes shutdown explicit/idempotent; locks stop/start race window.
src/ros2_medkit_gateway/src/core/http/parameter_error_classification.cpp	Derives possible statuses from enum; adds COUNT sentinel guard.
src/ros2_medkit_gateway/src/core/http/handlers/capability_builder.cpp	Types capability array as DTOs; fixes naming to served routes.
src/ros2_medkit_gateway/src/core/http/detail/primitives.cpp	Adds writer for already-serialized JSON text.
src/ros2_medkit_gateway/src/core/auth/auth_manager.cpp	Moves RBAC table to runtime-populated permission set.
src/ros2_medkit_gateway/README.md	Updates docs route semantics + graph provider endpoint details.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/http/typed_router.hpp	Clarifies TypedRequest::path() semantics (prefix included).
src/ros2_medkit_gateway/include/ros2_medkit_gateway/http/handlers/handler_support.hpp	Adds optional status recorder instrumentation for tests.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/http/handlers/fault_handlers.hpp	Declares classify_fault_failure API + rationale.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/http/handlers/cyclic_subscription_handlers.hpp	Documents Created<> contract for POST.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/http/handler_result.hpp	Introduces Created/Accepted wrappers + with_location.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/http/detail/primitives.hpp	Adds write_json_text API + clarifies legacy raw routes.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/http/alternate_status.hpp	Adds wrapper alternate-status + payload unwrap helpers.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/dto/x_medkit.hpp	Types embedded capabilities as EntityCapability list.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/dto/updates.hpp	Improves schema fidelity for SOVD update DTOs.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/dto/scripts.hpp	Removes unreachable schema; adds ScriptExecutionRequest DTO.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/dto/operations.hpp	Adds field descriptions; improves opaque result schema docs.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/dto/logs.hpp	Clarifies semantics; adds constraints/docs for fields.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/dto/locks.hpp	Adds detailed field docs + minimum constraint.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/dto/health.hpp	Documents timestamp semantics (wall-clock, non-monotonic).
src/ros2_medkit_gateway/include/ros2_medkit_gateway/dto/enums.hpp	Adds fault-trigger operator/severity vocab tables.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/dto/entity_capability.hpp	New typed DTO for capability list items.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/dto/data.hpp	Removes unreachable schema; models plugin-vs-core list via anyOf.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/dto/cyclic_subscriptions.hpp	Adds docs + minimum constraints for create/update.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/dto/contract.hpp	Adds FieldConstraints for schema-level bounds.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/dto/auth.hpp	Adds OAuth2Error DTO for RFC6749 error bodies.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/core/openapi/document_checks.hpp	Adds schema reachability/ref-walk utilities.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/core/models/entity_types.hpp	Expands/clarifies ResourceCollection contract + comments.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/core/models/entity_capabilities.hpp	Clarifies served-matrix intent vs spec-permitted superset.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/core/managers/update_manager.hpp	Documents notifier lifetime + adds shutdown() API.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/core/http/rest_server.hpp	Adds reporting hook for route metadata completeness issues.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/core/http/parameter_error_classification.hpp	Exposes derived status surface for parameter routes.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/core/http/http_utils.hpp	Adds canonical path + child-resource Location helpers.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/core/http/handlers/update_handlers.hpp	Updates signatures to Created/Accepted wrappers.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/core/http/handlers/trigger_handlers.hpp	Updates signatures/docs for Created<> POST.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/core/http/handlers/script_handlers.hpp	Updates signatures for Created/Accepted wrappers.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/core/http/handlers/operation_handlers.hpp	Makes 202 Accepted explicit in return type.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/core/http/handlers/lock_handlers.hpp	Updates POST signature/docs for Created<> + Location.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/core/http/handlers/lifecycle_handlers.hpp	Updates transition signature to Accepted<>.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/core/http/handlers/docs_handlers.hpp	Makes /docs root typed; keeps scoped docs raw.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/core/http/handlers/capability_builder.hpp	Types capability builder output; documents enumerator contract.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/core/http/handlers/bulkdata_handlers.hpp	Adds download_media_types() API; Created<> upload signature.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/core/http/error_codes.hpp	Adds x-medkit-resource-sample-failed code constant.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/core/faults/fault_types.hpp	Adds typed FaultFailure + defaults for safe classification.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/core/discovery/models/component.hpp	Fixes relationship key to /hosts.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/core/discovery/models/area.hpp	Fixes relationship key to /components.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/core/configuration/parameter_types.hpp	Adds COUNT sentinel for enum completeness enforcement.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/core/auth/auth_manager.hpp	Adds permission merge API + exposes auth policy accessor.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/core/auth/auth_config.hpp	Defines residual permissions + RoutePermissions type.
src/ros2_medkit_gateway/design/lifecycle.rst	Updates docs for Accepted<>-declared 202.
src/ros2_medkit_gateway/design/index.rst	Adds OpenAPI derivation doc + teardown contract note.
src/ros2_medkit_gateway/design/aggregation.rst	Clarifies fan-out header handling + known global-faults loop risk.
src/ros2_medkit_gateway/config/gateway_params.yaml	Documents updates backend gating as 501, not unregistered routes.
src/ros2_medkit_gateway/CMakeLists.txt	Adds status-recorder define (test-only) + new linter/contract tests.
src/ros2_medkit_fault_manager/test/test_rosbag_capture.cpp	Adds NAME_MAX budget tests; reserves vector capacity.
src/ros2_medkit_fault_manager/src/sqlite_fault_storage.cpp	Deletes move ops for stmt wrapper; documents intent.
src/ros2_medkit_fault_manager/src/fault_manager_node.cpp	Raises max fault_code length to 256; documents rationale.
src/ros2_medkit_fault_manager/src/fault_audit_log.cpp	Deletes move ops for stmt wrapper; documents intent.
src/ros2_medkit_fault_manager/include/ros2_medkit_fault_manager/rosbag_capture.hpp	Adds bounded+digest bag directory naming contract.
docs/tutorials/snapshots.rst	Documents bag directory name truncation + digest behavior.
docs/tutorials/plugin-system.rst	Documents describe_plugin_routes for OpenAPI inclusion.
docs/tutorials/graph-provider.rst	Clarifies plugin-conditional graph link behavior.
docs/tutorials/authentication.rst	Updates RBAC explanation + per-deployment doc behavior.
docs/config/server.rst	Updates updates.enabled semantics (501 gating, always registered).

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.