From f5cb3cde5a24115dd7ce6eba878fbccae8f129c5 Mon Sep 17 00:00:00 2001
From: Antoine Gersant <antoine.gersant@lesforges.org>
Date: Wed, 15 Jan 2025 22:47:15 -0800
Subject: [PATCH] Utoipa polish

---
 src/server/axum/api.rs | 6 +++---
 src/server/dto/v8.rs   | 3 ++-
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/src/server/axum/api.rs b/src/server/axum/api.rs
index b0661b2d..3a70ca46 100644
--- a/src/server/axum/api.rs
+++ b/src/server/axum/api.rs
@@ -1024,7 +1024,7 @@ async fn get_playlists(
 		("auth_token" = []),
 		("auth_query_param" = []),
 	),
-	params(("name",)),
+	params(("name", example = "Chill Jazz")),
 	request_body = dto::SavePlaylistInput,
 )]
 async fn put_playlist(
@@ -1057,7 +1057,7 @@ async fn put_playlist(
 	),
 	params(
 		("Accept-Version" = Option<i32>, Header, minimum = 7, maximum = 8),
-		("name",),
+		("name", example = "Chill Jazz"),
 	),
 	responses(
 		(status = 200, body = dto::Playlist),
@@ -1097,7 +1097,7 @@ async fn get_playlist(
 		("auth_token" = []),
 		("auth_query_param" = []),
 	),
-	params(("name",)),
+	params(("name", example = "Chill Jazz")),
 )]
 async fn delete_playlist(
 	auth: Auth,
diff --git a/src/server/dto/v8.rs b/src/server/dto/v8.rs
index 9c883862..692d74a0 100644
--- a/src/server/dto/v8.rs
+++ b/src/server/dto/v8.rs
@@ -48,7 +48,6 @@ pub struct AuthQueryParameters {
 
 #[derive(Serialize, Deserialize, IntoParams, ToSchema)]
 pub struct ThumbnailOptions {
-	#[schema(examples("tiny", "small", "large", "native"))]
 	pub size: Option<ThumbnailSize>,
 	#[schema(examples(true, false))]
 	pub pad: Option<bool>,
@@ -65,6 +64,7 @@ impl From<ThumbnailOptions> for thumbnail::Options {
 
 #[derive(Clone, Copy, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
+#[schema(example = "small")]
 pub enum ThumbnailSize {
 	Tiny,
 	Small,
@@ -321,6 +321,7 @@ impl From<index::Song> for Song {
 pub struct SongList {
 	#[schema(value_type = Vec<String>, examples(json!(["my_music/destiny.mp3", "my_music/sos.mp3"])))]
 	pub paths: Vec<PathBuf>,
+	/// Detailed metadata about the first few hundred songs listed in `.paths`
 	pub first_songs: Vec<Song>,
 }