fix: add OpenAPI documentation to API endpoints and integrate Swagger UI

Co-authored-by: aider (openai/andrew/openrouter/qwen/qwen3-coder) <aider@aider.chat>

src/modes/server/api/item.rs

@@ -11,11 +11,30 @@ use std::path::PathBuf;
 use std::str::FromStr;
 use std::io::Read;
 use anyhow::{Result, anyhow};
+use utoipa::ToSchema;
 
 use crate::compression_engine::{CompressionType, get_compression_engine};
 use crate::db;
 use crate::modes::server::common::{AppState, ApiResponse, ItemInfo, TagsQuery, check_auth, ListItemsQuery};
 
+#[utoipa::path(
+    get,
+    path = "/api/item/",
+    responses(
+        (status = 200, description = "Successfully retrieved list of items", body = ApiResponse<Vec<ItemInfo>>),
+        (status = 401, description = "Unauthorized"),
+        (status = 500, description = "Internal server error")
+    ),
+    params(
+        ("tags" = Option<String>, Query, description = "Comma-separated list of tags to filter by"),
+        ("order" = Option<String>, Query, description = "Sort order (newest or oldest)"),
+        ("start" = Option<u64>, Query, description = "Starting index for pagination"),
+        ("count" = Option<u64>, Query, description = "Number of items to return")
+    ),
+    security(
+        ("bearerAuth" = [])
+    )
+)]
 pub async fn handle_list_items(
     State(state): State<AppState>,
     Query(params): Query<ListItemsQuery>,
@@ -106,6 +125,18 @@ pub async fn handle_list_items(
     Ok(Json(response))
 }
 
+#[utoipa::path(
+    post,
+    path = "/api/item/",
+    responses(
+        (status = 200, description = "Successfully created item", body = ApiResponse<ItemInfo>),
+        (status = 401, description = "Unauthorized"),
+        (status = 500, description = "Internal server error")
+    ),
+    security(
+        ("bearerAuth" = [])
+    )
+)]
 pub async fn handle_post_item(
     State(state): State<AppState>,
     headers: HeaderMap,
@@ -129,6 +160,22 @@ pub async fn handle_post_item(
     Ok(Json(response))
 }
 
+#[utoipa::path(
+    delete,
+    path = "/api/item/{item_id}",
+    responses(
+        (status = 200, description = "Successfully deleted item", body = ApiResponse<()>),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Item not found"),
+        (status = 500, description = "Internal server error")
+    ),
+    params(
+        ("item_id" = String, Path, description = "ID of the item to delete")
+    ),
+    security(
+        ("bearerAuth" = [])
+    )
+)]
 pub async fn handle_delete_item(
     State(state): State<AppState>,
     Path(item_id): Path<String>,
@@ -166,6 +213,22 @@ pub async fn handle_delete_item(
     }
 }
 
+#[utoipa::path(
+    get,
+    path = "/api/item/latest",
+    responses(
+        (status = 200, description = "Successfully retrieved latest item content", body = ApiResponse<String>),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Item not found"),
+        (status = 500, description = "Internal server error")
+    ),
+    params(
+        ("tags" = Option<String>, Query, description = "Comma-separated list of tags to filter by")
+    ),
+    security(
+        ("bearerAuth" = [])
+    )
+)]
 pub async fn handle_get_item_latest(
     State(state): State<AppState>,
     Query(params): Query<TagsQuery>,
@@ -218,6 +281,22 @@ pub async fn handle_get_item_latest(
     }
 }
 
+#[utoipa::path(
+    get,
+    path = "/api/item/{item_id}",
+    responses(
+        (status = 200, description = "Successfully retrieved item content", body = ApiResponse<String>),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Item not found"),
+        (status = 500, description = "Internal server error")
+    ),
+    params(
+        ("item_id" = String, Path, description = "ID of the item to retrieve")
+    ),
+    security(
+        ("bearerAuth" = [])
+    )
+)]
 pub async fn handle_get_item(
     State(state): State<AppState>,
     Path(item_id): Path<String>,
@@ -269,6 +348,22 @@ pub async fn handle_get_item(
     }
 }
 
+#[utoipa::path(
+    get,
+    path = "/api/item/latest/content",
+    responses(
+        (status = 200, description = "Successfully retrieved latest item raw content"),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Item not found"),
+        (status = 500, description = "Internal server error")
+    ),
+    params(
+        ("tags" = Option<String>, Query, description = "Comma-separated list of tags to filter by")
+    ),
+    security(
+        ("bearerAuth" = [])
+    )
+)]
 pub async fn handle_get_item_latest_content(
     State(state): State<AppState>,
     Query(params): Query<TagsQuery>,
@@ -316,6 +411,22 @@ pub async fn handle_get_item_latest_content(
     }
 }
 
+#[utoipa::path(
+    get,
+    path = "/api/item/{item_id}/content",
+    responses(
+        (status = 200, description = "Successfully retrieved item raw content"),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Item not found"),
+        (status = 500, description = "Internal server error")
+    ),
+    params(
+        ("item_id" = String, Path, description = "ID of the item to retrieve")
+    ),
+    security(
+        ("bearerAuth" = [])
+    )
+)]
 pub async fn handle_get_item_content(
     State(state): State<AppState>,
     Path(item_id): Path<String>,
@@ -416,6 +527,22 @@ async fn get_item_raw_content(item: &db::Item, data_dir: &PathBuf, conn: &mut ru
     Ok((content, mime_type))
 }
 
+#[utoipa::path(
+    get,
+    path = "/api/item/latest/meta",
+    responses(
+        (status = 200, description = "Successfully retrieved latest item metadata", body = ApiResponse<HashMap<String, String>>),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Item not found"),
+        (status = 500, description = "Internal server error")
+    ),
+    params(
+        ("tags" = Option<String>, Query, description = "Comma-separated list of tags to filter by")
+    ),
+    security(
+        ("bearerAuth" = [])
+    )
+)]
 pub async fn handle_get_item_latest_meta(
     State(state): State<AppState>,
     Query(params): Query<TagsQuery>,
@@ -465,6 +592,22 @@ pub async fn handle_get_item_latest_meta(
     }
 }
 
+#[utoipa::path(
+    get,
+    path = "/api/item/{item_id}/meta",
+    responses(
+        (status = 200, description = "Successfully retrieved item metadata", body = ApiResponse<HashMap<String, String>>),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Item not found"),
+        (status = 500, description = "Internal server error")
+    ),
+    params(
+        ("item_id" = String, Path, description = "ID of the item to retrieve metadata for")
+    ),
+    security(
+        ("bearerAuth" = [])
+    )
+)]
 pub async fn handle_get_item_meta(
     State(state): State<AppState>,
     Path(item_id): Path<String>,