docs: add API documentation for websocket connection

src/main.rs

@@ -75,7 +75,7 @@ async fn main() {
         .routes(routes!(routes::book_instance::create_book_instance))
         .routes(routes!(routes::owner::get_owner_by_id))
         .routes(routes!(routes::owner::create_owner))
-        .route("/ws", get(routes::websocket::ws_handler))
+        .routes(routes!(routes::websocket::ws_handler))
         .route("/", get(index))
         .with_state(shared_state)
         .split_for_parts();

src/routes/websocket.rs

@@ -1,20 +1,29 @@
 use std::{net::SocketAddr, ops::ControlFlow, sync::Arc};
 
 use axum::{
-    body::Bytes,
-    extract::{
+    body::Bytes, extract::{
         ws::{Message, Utf8Bytes, WebSocket, WebSocketUpgrade},
         ConnectInfo,
         State
-    },
-    response::IntoResponse
+    }, http, response::IntoResponse
 };
+use reqwest::StatusCode;
 
 use crate::{utils::events, AppState};
 
 use futures_util::{sink::SinkExt, stream::StreamExt};
 
 #[axum::debug_handler]
+#[utoipa::path(
+    get,
+    path = "/ws",
+    responses(
+        (status = SWITCHING_PROTOCOLS, description = "Succesfully reached the websocket, now upgrade to establish the connection"),
+    ),
+    summary = "Connect to the websocket",
+    description = "Initial connection to the websocket before upgrading protocols",
+    tag = "websocket",
+)]
 pub async fn ws_handler(
     ws: WebSocketUpgrade,
     ConnectInfo(addr): ConnectInfo<SocketAddr>,