tsk-56: API documentation (#57)

Closes #56

Reviewed-on: phoenix/icarus_auth#57
Co-authored-by: phoenix <kundeng00@pm.me>
Co-committed-by: phoenix <kundeng00@pm.me>

src/callers/common.rs

@@ -1,7 +1,7 @@
 pub mod response {
     use serde::{Deserialize, Serialize};
 
-    #[derive(Deserialize, Serialize)]
+    #[derive(Deserialize, Serialize, utoipa::ToSchema)]
     pub struct TestResult {
         pub message: String,
     }
@@ -11,11 +11,28 @@ pub mod endpoint {
     use super::*;
     use axum::{Extension, Json, http::StatusCode};
 
-    // basic handler that responds with a static string
+    /// Endpoint to hit the root
+    /// basic handler that responds with a static string
+    #[utoipa::path(
+        get,
+        path = super::super::endpoints::ROOT,
+        responses(
+            (status = 200, description = "Test", body = &str),
+        )
+    )]
     pub async fn root() -> &'static str {
         "Hello, World!"
     }
 
+    /// Endpoint to do a database ping
+    #[utoipa::path(
+        get,
+        path = super::super::endpoints::DBTEST,
+        responses(
+            (status = 200, description = "Successful ping of the db", body = super::response::TestResult),
+            (status = 400, description = "Failure in pinging the db", body = super::response::TestResult)
+        )
+    )]
     pub async fn db_ping(
         Extension(pool): Extension<sqlx::PgPool>,
     ) -> (StatusCode, Json<response::TestResult>) {