pinakes-server: add utoipa annotations to all routes; fix tests

Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: I28cf5b7b7cff8e90e123d624d97cf9656a6a6964

crates/pinakes-server/src/routes/users.rs

@@ -16,6 +16,17 @@ use crate::{
 };
 
 /// List all users (admin only)
+#[utoipa::path(
+    get,
+    path = "/api/v1/admin/users",
+    tag = "users",
+    responses(
+        (status = 200, description = "List of users", body = Vec<UserResponse>),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Forbidden"),
+    ),
+    security(("bearer_auth" = []))
+)]
 pub async fn list_users(
   State(state): State<AppState>,
 ) -> Result<Json<Vec<UserResponse>>, ApiError> {
@@ -24,6 +35,24 @@ pub async fn list_users(
 }
 
 /// Create a new user (admin only)
+#[utoipa::path(
+    post,
+    path = "/api/v1/admin/users",
+    tag = "users",
+    request_body(
+        content = inline(serde_json::Value),
+        description = "username, password, role, and optional profile fields",
+        content_type = "application/json"
+    ),
+    responses(
+        (status = 200, description = "User created", body = UserResponse),
+        (status = 400, description = "Bad request"),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Forbidden"),
+        (status = 500, description = "Internal server error"),
+    ),
+    security(("bearer_auth" = []))
+)]
 pub async fn create_user(
   State(state): State<AppState>,
   Json(req): Json<CreateUserRequest>,
@@ -74,6 +103,19 @@ pub async fn create_user(
 }
 
 /// Get a specific user by ID
+#[utoipa::path(
+    get,
+    path = "/api/v1/admin/users/{id}",
+    tag = "users",
+    params(("id" = String, Path, description = "User ID")),
+    responses(
+        (status = 200, description = "User details", body = UserResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Forbidden"),
+        (status = 404, description = "Not found"),
+    ),
+    security(("bearer_auth" = []))
+)]
 pub async fn get_user(
   State(state): State<AppState>,
   Path(id): Path<String>,
@@ -90,6 +132,25 @@ pub async fn get_user(
 }
 
 /// Update a user
+#[utoipa::path(
+    patch,
+    path = "/api/v1/admin/users/{id}",
+    tag = "users",
+    params(("id" = String, Path, description = "User ID")),
+    request_body(
+        content = inline(serde_json::Value),
+        description = "Optional password, role, or profile fields to update",
+        content_type = "application/json"
+    ),
+    responses(
+        (status = 200, description = "User updated", body = UserResponse),
+        (status = 400, description = "Bad request"),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Forbidden"),
+        (status = 404, description = "Not found"),
+    ),
+    security(("bearer_auth" = []))
+)]
 pub async fn update_user(
   State(state): State<AppState>,
   Path(id): Path<String>,
@@ -125,6 +186,19 @@ pub async fn update_user(
 }
 
 /// Delete a user (admin only)
+#[utoipa::path(
+    delete,
+    path = "/api/v1/admin/users/{id}",
+    tag = "users",
+    params(("id" = String, Path, description = "User ID")),
+    responses(
+        (status = 200, description = "User deleted"),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Forbidden"),
+        (status = 404, description = "Not found"),
+    ),
+    security(("bearer_auth" = []))
+)]
 pub async fn delete_user(
   State(state): State<AppState>,
   Path(id): Path<String>,
@@ -141,6 +215,18 @@ pub async fn delete_user(
 }
 
 /// Get user's accessible libraries
+#[utoipa::path(
+    get,
+    path = "/api/v1/admin/users/{id}/libraries",
+    tag = "users",
+    params(("id" = String, Path, description = "User ID")),
+    responses(
+        (status = 200, description = "User libraries", body = Vec<UserLibraryResponse>),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Forbidden"),
+    ),
+    security(("bearer_auth" = []))
+)]
 pub async fn get_user_libraries(
   State(state): State<AppState>,
   Path(id): Path<String>,
@@ -177,6 +263,20 @@ fn validate_root_path(path: &str) -> Result<(), ApiError> {
 }
 
 /// Grant library access to a user (admin only)
+#[utoipa::path(
+    post,
+    path = "/api/v1/admin/users/{id}/libraries",
+    tag = "users",
+    params(("id" = String, Path, description = "User ID")),
+    request_body = GrantLibraryAccessRequest,
+    responses(
+        (status = 200, description = "Access granted"),
+        (status = 400, description = "Bad request"),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Forbidden"),
+    ),
+    security(("bearer_auth" = []))
+)]
 pub async fn grant_library_access(
   State(state): State<AppState>,
   Path(id): Path<String>,
@@ -202,6 +302,20 @@ pub async fn grant_library_access(
 ///
 /// Uses a JSON body instead of a path parameter because `root_path` may contain
 /// slashes that conflict with URL routing.
+#[utoipa::path(
+    delete,
+    path = "/api/v1/admin/users/{id}/libraries",
+    tag = "users",
+    params(("id" = String, Path, description = "User ID")),
+    request_body = RevokeLibraryAccessRequest,
+    responses(
+        (status = 200, description = "Access revoked"),
+        (status = 400, description = "Bad request"),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Forbidden"),
+    ),
+    security(("bearer_auth" = []))
+)]
 pub async fn revoke_library_access(
   State(state): State<AppState>,
   Path(id): Path<String>,