From 404af8b157a132d27df0100599be7e2bca0c2cfe Mon Sep 17 00:00:00 2001 From: kdeng00 Date: Sat, 23 Aug 2025 16:48:52 -0400 Subject: [PATCH] tsk-170: Added the rest of the documentation --- src/callers/coverart.rs | 69 +++++++++++++++++++++-------------------- src/callers/metadata.rs | 48 +++++++++++++++------------- src/callers/song.rs | 7 +++-- src/main.rs | 25 +++++++++++++-- 4 files changed, 89 insertions(+), 60 deletions(-) diff --git a/src/callers/coverart.rs b/src/callers/coverart.rs index e804315..b386c1b 100644 --- a/src/callers/coverart.rs +++ b/src/callers/coverart.rs @@ -1,5 +1,5 @@ // TODO: Separate queue and coverart endpoints -#[derive(Debug, Default, serde::Deserialize, serde::Serialize)] +#[derive(Debug, Default, serde::Deserialize, serde::Serialize, utoipa::ToSchema)] pub struct CoverArtQueue { pub id: uuid::Uuid, pub song_queue_id: uuid::Uuid, @@ -575,17 +575,19 @@ pub mod endpoint { } } - /* + /// Endpoint to fetch cover art details #[utoipa::path( - post, + get, path = super::super::endpoints::QUEUECOVERART, - params(super::request::fetch_coverart_no_data::Params), + params( + ("id" = uuid::Uuid, Path, description = "Queued cover art Id"), + ("song_queue_id" = uuid::Uuid, Path, description = "Queued song Id") + ), responses( (status = 200, description = "Queued song linked", body = super::response::fetch_coverart_no_data::Response), (status = 400, description = "Linkage failed", body = super::response::fetch_coverart_no_data::Response) ) )] - */ pub async fn fetch_coverart_no_data( axum::Extension(pool): axum::Extension, axum::extract::Query(params): axum::extract::Query< @@ -635,7 +637,7 @@ pub mod endpoint { /// Endpoint to fetch the queued cover art data #[utoipa::path( - post, + get, path = super::super::endpoints::QUEUECOVERARTDATA, params(("id" = uuid::Uuid, Path, description = "Queued cover art Id")), responses( @@ -671,17 +673,18 @@ pub mod endpoint { } } + /// Endpoint to create cover art #[utoipa::path( post, - path = "/api/v2/song/queue/link", + path = super::super::endpoints::CREATECOVERART, request_body( - content = super::request::link_user_id::Request, - description = "User Id and queued song id", + content = super::request::create_coverart::Request, + description = "Data required to create cover art", content_type = "application/json" ), responses( - (status = 200, description = "Queued song linked", body = super::response::link_user_id::Response), - (status = 400, description = "Linkage failed", body = super::response::link_user_id::Response) + (status = 200, description = "Cover art created", body = super::response::create_coverart::Response), + (status = 400, description = "Failure in creating cover art", body = super::response::create_coverart::Response) ) )] pub async fn create_coverart( @@ -744,17 +747,19 @@ pub mod endpoint { } } + /// Endpoint to wipe data from the cover art queue #[utoipa::path( - post, - path = "/api/v2/song/queue/link", + patch, + path = super::super::endpoints::QUEUECOVERARTDATAWIPE, request_body( - content = super::request::link_user_id::Request, - description = "User Id and queued song id", + content = super::request::wipe_data_from_coverart_queue::Request, + description = "Data required to wipe the data from the cover art queue", content_type = "application/json" ), responses( - (status = 200, description = "Queued song linked", body = super::response::link_user_id::Response), - (status = 400, description = "Linkage failed", body = super::response::link_user_id::Response) + (status = 200, description = "Data wiped from cover art queue", body = super::response::wipe_data_from_coverart_queue::Response), + (status = 400, description = "Error wiping the data", body = super::response::wipe_data_from_coverart_queue::Response), + (status = 404, description = "Cover art not found", body = super::response::wipe_data_from_coverart_queue::Response) ) )] pub async fn wipe_data_from_coverart_queue( @@ -786,17 +791,16 @@ pub mod endpoint { } } + /// Endpoint to get cover art with criteria #[utoipa::path( - post, - path = "/api/v2/song/queue/link", - request_body( - content = super::request::link_user_id::Request, - description = "User Id and queued song id", - content_type = "application/json" + get, + path = super::super::endpoints::GETCOVERART, + params( + ("id" = uuid::Uuid, Path, description = "Cover art Id") ), responses( - (status = 200, description = "Queued song linked", body = super::response::link_user_id::Response), - (status = 400, description = "Linkage failed", body = super::response::link_user_id::Response) + (status = 200, description = "Cover art retrieved", body = super::response::get_coverart::Response), + (status = 400, description = "Error retrieving cover art", body = super::response::get_coverart::Response) ) )] pub async fn get_coverart( @@ -827,17 +831,16 @@ pub mod endpoint { } } + /// Endpoint to download cover art #[utoipa::path( - post, - path = "/api/v2/song/queue/link", - request_body( - content = super::request::link_user_id::Request, - description = "User Id and queued song id", - content_type = "application/json" + get, + path = super::super::endpoints::DOWNLOADCOVERART, + params( + ("id" = uuid::Uuid, Path, description = "Cover art Id") ), responses( - (status = 200, description = "Queued song linked", body = super::response::link_user_id::Response), - (status = 400, description = "Linkage failed", body = super::response::link_user_id::Response) + (status = 200, description = "Cover art downloading", body = Vec), + (status = 404, description = "Cover art not found", body = Vec) ) )] pub async fn download_coverart( diff --git a/src/callers/metadata.rs b/src/callers/metadata.rs index 20d9e7b..a509e6d 100644 --- a/src/callers/metadata.rs +++ b/src/callers/metadata.rs @@ -1,10 +1,9 @@ // TODO: Explicitly make this module target queueing a song's metadata pub mod request { - pub mod queue_metadata { use serde::{Deserialize, Serialize}; - #[derive(Debug, Default, Deserialize, Serialize, sqlx::FromRow)] + #[derive(Debug, Default, Deserialize, Serialize, sqlx::FromRow, utoipa::ToSchema)] pub struct Request { pub song_queue_id: uuid::Uuid, pub album: String, @@ -43,7 +42,13 @@ pub mod request { pub mod fetch_metadata { #[derive( - Debug, Default, serde::Deserialize, serde::Serialize, sqlx::FromRow, sqlx::Decode, + Debug, + Default, + serde::Deserialize, + serde::Serialize, + sqlx::FromRow, + sqlx::Decode, + utoipa::ToSchema, )] pub struct Params { pub id: Option, @@ -53,11 +58,10 @@ pub mod request { } pub mod response { - pub mod queue_metadata { use serde::{Deserialize, Serialize}; - #[derive(Default, Deserialize, Serialize)] + #[derive(Default, Deserialize, Serialize, utoipa::ToSchema)] pub struct Response { pub message: String, pub data: Vec, @@ -67,7 +71,7 @@ pub mod response { pub mod fetch_metadata { use serde::{Deserialize, Serialize}; - #[derive(Default, Deserialize, Serialize)] + #[derive(Default, Deserialize, Serialize, utoipa::ToSchema)] pub struct Response { pub message: String, pub data: Vec, @@ -83,7 +87,7 @@ pub mod metadata_queue { pub id: uuid::Uuid, } - #[derive(Debug, serde::Deserialize, serde::Serialize, sqlx::FromRow)] + #[derive(Debug, serde::Deserialize, serde::Serialize, sqlx::FromRow, utoipa::ToSchema)] pub struct MetadataQueue { pub id: uuid::Uuid, pub metadata: serde_json::Value, @@ -204,20 +208,22 @@ pub mod metadata_queue { } } +/// Module for metadata related endpoints pub mod endpoint { use axum::{Json, http::StatusCode}; + /// Endpoint to create queued metadata #[utoipa::path( post, - path = "/api/v2/song/queue/link", + path = super::super::endpoints::QUEUEMETADATA, request_body( - content = super::request::link_user_id::Request, - description = "User Id and queued song id", + content = super::request::queue_metadata::Request, + description = "Data required to create queued metadata", content_type = "application/json" ), responses( - (status = 200, description = "Queued song linked", body = super::response::link_user_id::Response), - (status = 400, description = "Linkage failed", body = super::response::link_user_id::Response) + (status = 200, description = "Queued metadata created", body = super::response::queue_metadata::Response), + (status = 400, description = "Error creating queued metadata", body = super::response::queue_metadata::Response) ) )] pub async fn queue_metadata( @@ -234,7 +240,7 @@ pub mod endpoint { response.message = if response.data.is_empty() { String::from("Error") } else { - String::from("Success") + String::from(super::super::response::SUCCESSFUL) }; (StatusCode::OK, Json(response)) @@ -246,17 +252,17 @@ pub mod endpoint { } } + /// Endpoint to get queued metadata #[utoipa::path( - post, - path = "/api/v2/song/queue/link", - request_body( - content = super::request::link_user_id::Request, - description = "User Id and queued song id", - content_type = "application/json" + get, + path = super::super::endpoints::QUEUEMETADATA, + params( + ("id" = uuid::Uuid, Path, description = "Id of queued metadata"), + ("song_queue_id" = uuid::Uuid, Path, description = "Id of queued song") ), responses( - (status = 200, description = "Queued song linked", body = super::response::link_user_id::Response), - (status = 400, description = "Linkage failed", body = super::response::link_user_id::Response) + (status = 200, description = "Queued metadata retrieved", body = super::response::fetch_metadata::Response), + (status = 400, description = "Error retrieving queued metadata", body = super::response::fetch_metadata::Response) ) )] pub async fn fetch_metadata( diff --git a/src/callers/song.rs b/src/callers/song.rs index e3def6f..2051fda 100644 --- a/src/callers/song.rs +++ b/src/callers/song.rs @@ -1323,17 +1323,18 @@ pub mod endpoint { } } - /* + // Endpoint to get songs #[utoipa::path( get, path = super::super::endpoints::GETSONGS, - params(super::request::get_songs::Params), + params( + ("id" = uuid::Uuid, Path, description = "Id of song") + ), responses( (status = 200, description = "Songs found", body = super::response::get_songs::Response), (status = 400, description = "Error getting songs", body = super::response::get_songs::Response) ) )] - */ pub async fn get_songs( axum::Extension(pool): axum::Extension, axum::extract::Query(params): axum::extract::Query, diff --git a/src/main.rs b/src/main.rs index 008aa4d..369894f 100644 --- a/src/main.rs +++ b/src/main.rs @@ -55,14 +55,33 @@ pub mod init { header::{ACCEPT, AUTHORIZATION, CONTENT_TYPE}, }; + use crate::callers::coverart as coverart_caller; + use crate::callers::metadata as metadata_caller; use crate::callers::song as song_caller; + use coverart_caller::endpoint as coverart_endpoints; + use coverart_caller::response as coverart_responses; + use metadata_caller::endpoint as metadata_endpoints; + use metadata_caller::response as metadata_responses; + use song_caller::endpoint as song_endpoints; + use song_caller::response as song_responses; #[derive(utoipa::OpenApi)] #[openapi( - paths(song_caller::endpoint::queue_song, song_caller::endpoint::link_user_id), - components(schemas(song_caller::response::Response, song_caller::response::link_user_id::Response)), + paths(song_endpoints::queue_song, song_endpoints::link_user_id, song_endpoints::fetch_queue_song, song_endpoints::download_flac, + song_endpoints::update_song_queue_status, song_endpoints::update_song_queue, song_endpoints::create_metadata, song_endpoints::wipe_data_from_song_queue, song_endpoints::get_songs, song_endpoints::get_all_songs, song_endpoints::stream_song, song_endpoints::download_song, + song_endpoints::delete_song, coverart_endpoints::queue, coverart_endpoints::link, coverart_endpoints::fetch_coverart_no_data, + coverart_endpoints::fetch_coverart_with_data, coverart_endpoints::create_coverart, coverart_endpoints::wipe_data_from_coverart_queue, + coverart_endpoints::get_coverart, coverart_endpoints::download_coverart, + metadata_endpoints::queue_metadata, metadata_endpoints::fetch_metadata), + components(schemas(song_responses::Response, song_responses::link_user_id::Response, song_responses::fetch_queue_song::Response, + song_responses::update_status::Response, song_responses::update_song_queue::Response, song_responses::create_metadata::Response, + song_responses::wipe_data_from_song_queue::Response, song_responses::get_songs::Response, song_responses::delete_song::Response, + coverart_responses::Response, coverart_responses::link::Response, coverart_responses::fetch_coverart_no_data::Response, + coverart_responses::fetch_coverart_with_data::Response, coverart_responses::create_coverart::Response, + coverart_responses::wipe_data_from_coverart_queue::Response, coverart_responses::get_coverart::Response, + metadata_responses::queue_metadata::Response, metadata_responses::fetch_metadata::Response)), tags( - (name = "queue song", description = "Start process to upload song by queueing the song") + (name = "Icarus API", description = "Web API to manage music") ) )] struct ApiDoc;