Description
api-server/src/main.rs's ApiDoc (lines 33-61) declares the OpenAPI spec surfaced at /openapi.json and Swagger UI at /docs:
#[derive(OpenApi)]
#[openapi(
paths(
crate::handlers::health,
crate::handlers::simulate,
crate::handlers::list_routes,
crate::handlers::get_route,
),
...
)]
struct ApiDoc;The router registers five routes (lines 138-142): /health, /simulate, /routes, /routes/:name, and /ws. Only the first four appear in paths(...); websocket::ws_handler (websocket.rs line 23) — the /ws route — has no #[utoipa::path(...)] annotation and is absent from ApiDoc.
Impact
Anyone browsing the generated Swagger UI (/docs) or openapi.json has no indication that a /ws WebSocket endpoint exists at all, let alone how to use it (the SubscribeMessage/{"action":"subscribe","tx_id":...} protocol, or the status_update/subscribed/error message shapes sent back). It's the only route in the server with zero API documentation.
Suggested fix
Add a #[utoipa::path(get, path = "/ws", ...)] annotation on ws_handler describing it as a WebSocket upgrade endpoint (utoipa supports documenting such endpoints as a plain GET for discovery purposes even though the protocol switch itself isn't representable in OpenAPI), include it in ApiDoc's paths(...), and add SubscribeMessage to components(schemas(...)) (note: SubscribeMessage doesn't currently derive ToSchema either — see types.rs lines 170-174 — so that would need adding too) so the subscribe/unsubscribe message shape is documented alongside the endpoint.
Description
api-server/src/main.rs'sApiDoc(lines 33-61) declares the OpenAPI spec surfaced at/openapi.jsonand Swagger UI at/docs:The router registers five routes (lines 138-142):
/health,/simulate,/routes,/routes/:name, and/ws. Only the first four appear inpaths(...);websocket::ws_handler(websocket.rs line 23) — the/wsroute — has no#[utoipa::path(...)]annotation and is absent fromApiDoc.Impact
Anyone browsing the generated Swagger UI (
/docs) oropenapi.jsonhas no indication that a/wsWebSocket endpoint exists at all, let alone how to use it (theSubscribeMessage/{"action":"subscribe","tx_id":...}protocol, or thestatus_update/subscribed/errormessage shapes sent back). It's the only route in the server with zero API documentation.Suggested fix
Add a
#[utoipa::path(get, path = "/ws", ...)]annotation onws_handlerdescribing it as a WebSocket upgrade endpoint (utoipa supports documenting such endpoints as a plainGETfor discovery purposes even though the protocol switch itself isn't representable in OpenAPI), include it inApiDoc'spaths(...), and addSubscribeMessagetocomponents(schemas(...))(note:SubscribeMessagedoesn't currently deriveToSchemaeither — seetypes.rslines 170-174 — so that would need adding too) so the subscribe/unsubscribe message shape is documented alongside the endpoint.