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/album.rs | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 50 insertions(+), 1 deletion(-)

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

diff --git a/src/api/album.rs b/src/api/album.rs
index 9094495..f8731fb 100644
--- a/src/api/album.rs
+++ b/src/api/album.rs
@@ -5,15 +5,25 @@ 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 ( /album?arg=value ) */
-#[derive(Deserialize)]
+#[derive(Deserialize, IntoParams)]
 struct AlbumQueryOptions {
     id: Option<String>,
     name: Option<String>,
     artist: Option<String>,
 }
 
+#[utoipa::path(
+    params(AlbumQueryOptions),
+    context_path = "/api",
+    description = "Gets a list of the current albums 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 albums", body = Vec<Album>),
+        (status = 400, description = "Errors found, unfulfilled request"),
+    ),
+)]
 #[get("/album")]
 pub async fn get_album(
     app_state: web::Data<AppState>,
@@ -53,6 +63,19 @@ pub async fn get_album(
     }
 }
 
+#[utoipa::path(
+    request_body = AlbumPost,
+    context_path = "/api",
+    description = "Creates a new album with the specified values.",
+    responses(
+        (status = 200, description = "Create new album", body = Response),
+        (status = 400, description = "Errors found, unfulfilled request"),
+        (status = 401, description = "Authentication failed"),
+    ),
+    security(
+        {"bearer_auth" = []}
+    ),
+)]
 #[post("/album")]
 pub async fn post_album(
     app_state: web::Data<AppState>,
@@ -68,6 +91,19 @@ pub async fn post_album(
     )
 }
 
+#[utoipa::path(
+    request_body = AlbumPut,
+    context_path = "/api",
+    description = "Edits the values of the specified album.",
+    responses(
+        (status = 200, description = "Edit album values", body = Response),
+        (status = 400, description = "Errors found or album not found"),
+        (status = 401, description = "Authentication failed"),
+    ),
+    security(
+        {"bearer_auth" = []}
+    ),
+)]
 #[put("/album")]
 pub async fn put_album(
     app_state: web::Data<AppState>,
@@ -83,6 +119,19 @@ pub async fn put_album(
     )
 }
 
+#[utoipa::path(
+    request_body = Delete,
+    context_path = "/api",
+    description = "Deletes the specified album.",
+    responses(
+        (status = 200, description = "Delete existing album", body = Response),
+        (status = 400, description = "Errors found or album not found"),
+        (status = 401, description = "Authentication failed"),
+    ),
+    security(
+        {"bearer_auth" = []}
+    ),
+)]
 #[delete("/album")]
 pub async fn delete_album(
     app_state: web::Data<AppState>,
-- 
cgit v1.2.3