diff --git a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/delete/delete_media_file_handler.rs b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/delete/delete_media_file_handler.rs index d293598740..c7d441df88 100644 --- a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/delete/delete_media_file_handler.rs +++ b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/delete/delete_media_file_handler.rs @@ -64,6 +64,7 @@ impl fmt::Display for DeleteMediaFileError { // =============== Handler =============== +/// Delete a media file. (Files and records are soft deleted.) #[utoipa::path( delete, tag = "Media Files", diff --git a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/edit/change_media_file_visibility_handler.rs b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/edit/change_media_file_visibility_handler.rs index cec94dbf63..47c43646c4 100644 --- a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/edit/change_media_file_visibility_handler.rs +++ b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/edit/change_media_file_visibility_handler.rs @@ -63,6 +63,7 @@ impl fmt::Display for ChangeMediaFileVisibilityError { // =============== Handler =============== +/// Change the visibility (public, hidden, private) of a media file. #[utoipa::path( post, tag = "Media Files", diff --git a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/edit/rename_media_file_handler.rs b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/edit/rename_media_file_handler.rs index 3c35a1d182..f9855a55b0 100644 --- a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/edit/rename_media_file_handler.rs +++ b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/edit/rename_media_file_handler.rs @@ -65,6 +65,7 @@ impl fmt::Display for RenameMediaFileError { // =============== Handler =============== +/// Change (or remove) the "title" of a media file. #[utoipa::path( post, tag = "Media Files", diff --git a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/edit/set_media_file_cover_image_handler.rs b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/edit/set_media_file_cover_image_handler.rs index 051b45405f..4f5376b29b 100644 --- a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/edit/set_media_file_cover_image_handler.rs +++ b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/edit/set_media_file_cover_image_handler.rs @@ -68,6 +68,10 @@ impl fmt::Display for SetMediaFileCoverImageError { // =============== Handler =============== +/// Set or remove the "cover image" (which are used as thumbnails) on a file. +/// +/// The cover image is another media file of media_class = image. It can be anything in the database, +/// you'll just need its media file token. #[utoipa::path( post, tag = "Media Files", diff --git a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/get/batch_get_media_files_handler.rs b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/get/batch_get_media_files_handler.rs index 9f6d9790ee..a28130abd5 100644 --- a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/get/batch_get_media_files_handler.rs +++ b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/get/batch_get_media_files_handler.rs @@ -210,6 +210,7 @@ impl fmt::Display for BatchGetMediaFilesError { // =============== Handler =============== +/// List many media files at the same time by supplying their tokens. You'll have to provide the tokens. #[utoipa::path( get, tag = "Media Files", diff --git a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/get/get_media_file_handler.rs b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/get/get_media_file_handler.rs index 398ea539a2..04bc79082d 100644 --- a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/get/get_media_file_handler.rs +++ b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/get/get_media_file_handler.rs @@ -192,6 +192,7 @@ impl fmt::Display for GetMediaFileError { } } +/// Get a single media file by token. #[utoipa::path( get, tag = "Media Files", diff --git a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_featured_media_files_handler.rs b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_featured_media_files_handler.rs index 787bcfae22..b6d4542866 100644 --- a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_featured_media_files_handler.rs +++ b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_featured_media_files_handler.rs @@ -124,6 +124,7 @@ impl ResponseError for ListFeaturedMediaFilesError { } } +/// List media files that were featured or promoted by the staff (paginated). This will power our global asset drawers and highlight reels. #[utoipa::path( get, tag = "Media Files", diff --git a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_media_files_by_batch_token_handler.rs b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_media_files_by_batch_token_handler.rs index f688590247..68ab1fd380 100644 --- a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_media_files_by_batch_token_handler.rs +++ b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_media_files_by_batch_token_handler.rs @@ -147,6 +147,10 @@ impl std::fmt::Display for ListMediaFilesByBatchError { } } +/// List media files that were generated together in a "batch", e.g. stable diffusion outputs. +/// +/// This uses a special "batch token" that these jobs return. Media files created together will also +/// return their batch token in the GET endpoint so that you can render a gallery of the batch outputs. #[utoipa::path( get, tag = "Media Files", diff --git a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_media_files_for_user_handler.rs b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_media_files_for_user_handler.rs index 998ace33f2..ab32e2f896 100644 --- a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_media_files_for_user_handler.rs +++ b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_media_files_for_user_handler.rs @@ -175,6 +175,10 @@ impl std::fmt::Display for ListMediaFilesForUserError { } } +/// List all of a user's media files (paginated). +/// +/// This endpoint uses the session to automatically show all files for the given user, but only +/// show "public" files for external users. #[utoipa::path( get, tag = "Media Files", diff --git a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_media_files_handler.rs b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_media_files_handler.rs index aeac312851..a3a1b1e6f2 100644 --- a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_media_files_handler.rs +++ b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_media_files_handler.rs @@ -177,6 +177,9 @@ impl std::fmt::Display for ListMediaFilesError { } } +/// List all media files in the system globally, across all users (paginated). +/// +/// This powers "explore files" page. #[utoipa::path( get, tag = "Media Files", diff --git a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/upload/upload_new_scene_media_file_handler.rs b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/upload/upload_new_scene_media_file_handler.rs index 3801bfc877..540758060f 100644 --- a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/upload/upload_new_scene_media_file_handler.rs +++ b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/upload/upload_new_scene_media_file_handler.rs @@ -67,6 +67,13 @@ pub struct UploadNewSceneMediaFileSuccessResponse { pub media_file_token: MediaFileToken, } +/// This endpoint is for saving a new scene for the first time. +/// +/// You'll get back a media token for accessing and querying the scene in the future. +/// +/// For future saving on the same scene, call the "saved scene" endpoint, i.e. do not +/// call this endpoint a second time unless the user wants to save a new copy of the +/// same scene. #[utoipa::path( post, tag = "Media Files", diff --git a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/upload/upload_saved_scene_media_file_handler.rs b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/upload/upload_saved_scene_media_file_handler.rs index 4a45f65d35..e4bf6d5671 100644 --- a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/upload/upload_saved_scene_media_file_handler.rs +++ b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/upload/upload_saved_scene_media_file_handler.rs @@ -67,6 +67,13 @@ pub struct UploadSavedSceneMediaFileSuccessResponse { pub media_file_token: MediaFileToken, } +/// Use this endpoint to make changes to an existing scene. +/// +/// If you have a media token for the scene you're trying to save (i.e. not a completely +/// new, unsaved scene), call this endpoint to overwrite and save the changes to the scene. +/// +/// If you want to create a new copy of an existing scene, call the "new scene" endpoint +/// instead as it won't overwrite an existing scene and will return a brand new media token. #[utoipa::path( post, tag = "Media Files", diff --git a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/upsert_upload/write_scene_file/write_scene_file_media_file_handler.rs b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/upsert_upload/write_scene_file/write_scene_file_media_file_handler.rs index 6212f5e811..98da13d177 100644 --- a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/upsert_upload/write_scene_file/write_scene_file_media_file_handler.rs +++ b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/upsert_upload/write_scene_file/write_scene_file_media_file_handler.rs @@ -39,6 +39,7 @@ pub struct WriteSceneFileMediaSuccessResponse { pub media_file_token: MediaFileToken, } +/// DEPRECATED: Use the "new scene" and "saved scene" endpoints instead. #[deprecated] #[utoipa::path( post,