From c622eab39ac7dd9f794b5d60eb937e29c9b3bd6e Mon Sep 17 00:00:00 2001
From: niliara-edu <nil.jimeno@estudiant.fjaverianas.com>
Date: Sun, 26 Jan 2025 19:11:24 +0100
Subject: add api documentation

---
 src/api/song.rs | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 50 insertions(+), 1 deletion(-)

(limited to 'src/api/song.rs')

diff --git a/src/api/song.rs b/src/api/song.rs
index 1fec41c..06bc4b6 100644
--- a/src/api/song.rs
+++ b/src/api/song.rs
@@ -5,9 +5,10 @@ use crate::extractors::auth_token::AuthenticationToken;
 use crate::AppState;
 use actix_web::{delete, get, post, put, web, HttpResponse};
 use serde::Deserialize;
+use utoipa::IntoParams;
 
 /* Possible arguments ( /song?arg=value ) */
-#[derive(Deserialize)]
+#[derive(Deserialize, IntoParams)]
 struct SongQueryOptions {
     id: Option<String>,
     name: Option<String>,
@@ -15,6 +16,15 @@ struct SongQueryOptions {
     album: Option<String>,
 }
 
+#[utoipa::path(
+    params(SongQueryOptions),
+    context_path = "/api",
+    description = "Gets a list of the current songs and applies filters based on the url parameters recieved. It only accepts one parameter at a time.",
+    responses(
+        (status = 200, description = "Return a list of songs", body = Vec<Song>),
+        (status = 400, description = "Errors found, unfulfilled request"),
+    ),
+)]
 #[get("/song")]
 pub async fn get_song(
     app_state: web::Data<AppState>,
@@ -58,6 +68,19 @@ pub async fn get_song(
     }
 }
 
+#[utoipa::path(
+    request_body = SongPost,
+    context_path = "/api",
+    description = "Creates a new song with the specified values.",
+    responses(
+        (status = 200, description = "Create new song", body = Response),
+        (status = 400, description = "Errors found, unfulfilled request"),
+        (status = 401, description = "Authentication failed"),
+    ),
+    security(
+        {"bearer_auth" = []}
+    ),
+)]
 #[post("/song")]
 pub async fn post_song(
     app_state: web::Data<AppState>,
@@ -73,6 +96,19 @@ pub async fn post_song(
     )
 }
 
+#[utoipa::path(
+    request_body = SongPut,
+    context_path = "/api",
+    description = "Edits the values of the specified song.",
+    responses(
+        (status = 200, description = "Edit song values", body = Response),
+        (status = 400, description = "Errors found or song not found"),
+        (status = 401, description = "Authentication failed"),
+    ),
+    security(
+        {"bearer_auth" = []}
+    ),
+)]
 #[put("/song")]
 pub async fn put_song(
     app_state: web::Data<AppState>,
@@ -88,6 +124,19 @@ pub async fn put_song(
     )
 }
 
+#[utoipa::path(
+    request_body = Delete,
+    context_path = "/api",
+    description = "Deletes the specified song.",
+    responses(
+        (status = 200, description = "Delete existing song", body = Response),
+        (status = 400, description = "Errors found or song not found"),
+        (status = 401, description = "Authentication failed"),
+    ),
+    security(
+        {"bearer_auth" = []}
+    ),
+)]
 #[delete("/song")]
 pub async fn delete_song(
     app_state: web::Data<AppState>,
-- 
cgit v1.2.3