@@ -676,3 +676,86 @@ async fn lfs_check_sub_oid_exist(
     let result = storage.get_lfs_relations_ori_oid(sub_oid).await.unwrap();
     Ok(!result.is_empty())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::lfs::lfs_structs::{Action, Ref, ResCondition, ResponseObject};
+
+    #[test]
+    fn response_object_download_existing() {
+        let meta = MetaObject {
+            oid: "oid1".into(),
+            size: 10,
+            exist: true,
+            splited: false,
+        };
+        let res = ResponseObject::new(
+            &meta,
+            ResCondition {
+                file_exist: true,
+                operation: Operation::Download,
+                use_tus: false,
+            },
+            "http://dl",
+            "http://ul",
+        );
+        assert!(res.actions.is_some());
+        let actions = res.actions.unwrap();
+        assert!(actions.contains_key(&Action::Download));
+        assert!(res.error.is_none());
+    }
+
+    #[test]
+    fn response_object_upload_new() {
+        let meta = MetaObject {
+            oid: "oid2".into(),
+            size: 20,
+            exist: false,
+            splited: false,
+        };
+        let res = ResponseObject::new(
+            &meta,
+            ResCondition {
+                file_exist: false,
+                operation: Operation::Upload,
+                use_tus: false,
+            },
+            "http://dl",
+            "http://ul",
+        );
+        let actions = res.actions.expect("upload should provide actions");
+        assert!(actions.contains_key(&Action::Upload));
+        assert!(res.error.is_none());
+    }
+
+    #[test]
+    fn response_object_download_missing_sets_error() {
+        let meta = MetaObject {
+            oid: "oid3".into(),
+            size: 30,
+            exist: false,
+            splited: false,
+        };
+        let res = ResponseObject::new(
+            &meta,
+            ResCondition {
+                file_exist: false,
+                operation: Operation::Download,
+                use_tus: false,
+            },
+            "http://dl",
+            "http://ul",
+        );
+        assert!(res.actions.is_none());
+        assert!(res.error.is_some());
+        assert_eq!(res.error.unwrap().code, 404);
+    }
+
+    #[test]
+    fn unlock_request_defaults() {
+        let req = UnlockRequest::default();
+        assert!(req.force.is_none());
+        assert_eq!(req.refs, Ref { name: "".into() });
+    }
+}
@@ -4,8 +4,9 @@ use chrono::{DateTime, Duration, Utc};
 use common::config::LFSConfig;
 use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
+use utoipa::ToSchema;
 
-#[derive(Serialize, Deserialize, Debug, Default)]
+#[derive(Serialize, Deserialize, Debug, Default, ToSchema)]
 pub enum TransferMode {
     #[default]
     #[serde(rename = "basic")]
@@ -16,7 +17,7 @@ pub enum TransferMode {
     STREAMING,
 }
 
-#[derive(Serialize, Deserialize, PartialEq, Eq, Hash, Debug, Clone)]
+#[derive(Serialize, Deserialize, PartialEq, Eq, Hash, Debug, Clone, ToSchema)]
 pub enum Operation {
     #[serde(rename = "download")]
     Download,
@@ -28,7 +29,7 @@ pub enum Operation {
 /// Upload operations can specify an upload and a verify action.
 /// The upload action describes how to upload the object. If the object has a verify action, the LFS client will hit this URL after a successful upload. Servers can use this for extra verification, if needed.
 /// If a client requests to upload an object that the server already has, the server should omit the actions property completely. The client will then assume the server already has it.
-#[derive(Serialize, Deserialize, PartialEq, Eq, Hash, Debug)]
+#[derive(Serialize, Deserialize, PartialEq, Eq, Hash, Debug, ToSchema)]
 pub enum Action {
     #[serde(rename = "download")]
     Download,
@@ -84,7 +85,8 @@ impl MetaObject {
     }
 }
 
-#[derive(Serialize, Deserialize, Debug, Default)]
+#[derive(Serialize, Deserialize, Debug, Default, ToSchema)]
+/// Request object for LFS operations
 pub struct RequestObject {
     pub oid: String,
     pub size: i64,
@@ -98,20 +100,23 @@ pub struct RequestObject {
     pub authorization: String,
 }
 
-#[derive(Serialize, Deserialize, Debug, Clone)]
+#[derive(Serialize, Deserialize, Debug, Clone, ToSchema)]
+/// LFS lock information
 pub struct Lock {
     pub id: String,
     pub path: String,
     pub locked_at: String,
     pub owner: Option<User>,
 }
 
-#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+/// User information for lock ownership
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, ToSchema)]
 pub struct User {
     pub name: String,
 }
 
-#[derive(Serialize, Deserialize, Debug)]
+#[derive(Serialize, Deserialize, Debug, ToSchema)]
+/// Batch request for LFS operations
 pub struct BatchRequest {
     // Should be download or upload.
     pub operation: Operation,
@@ -122,21 +127,24 @@ pub struct BatchRequest {
     pub hash_algo: String,
 }
 
-#[derive(Serialize, Deserialize)]
+#[derive(Serialize, Deserialize, ToSchema)]
+/// Batch response for LFS operations
 pub struct BatchResponse {
     pub transfer: TransferMode,
     pub objects: Vec<ResponseObject>,
     pub hash_algo: String,
 }
 
-#[derive(Serialize, Deserialize)]
-pub struct FetchchunkResponse {
+#[derive(Serialize, Deserialize, ToSchema)]
+/// Response for fetching chunk IDs
+pub struct FetchChunkResponse {
     pub oid: String,
     pub size: i64,
     pub chunks: Vec<ChunkDownloadObject>,
 }
 
-#[derive(Serialize, Deserialize, Clone)]
+#[derive(Serialize, Deserialize, Clone, ToSchema)]
+/// Link information for LFS object transfer
 pub struct Link {
     pub href: String,
     #[serde(default)] // Optional field
@@ -160,13 +168,15 @@ impl Link {
     }
 }
 
-#[derive(Serialize, Deserialize, Default)]
+#[derive(Serialize, Deserialize, Default, ToSchema)]
+/// Error information for LFS object operations
 pub struct ObjectError {
     pub code: i64,
     pub message: String,
 }
 
-#[derive(Serialize, Deserialize)]
+#[derive(Serialize, Deserialize, ToSchema)]
+/// Response object for LFS batch operations
 pub struct ResponseObject {
     pub oid: String,
     pub size: i64,
@@ -261,67 +271,77 @@ impl ResponseObject {
     }
 }
 
-#[derive(Serialize, Deserialize)]
+#[derive(Serialize, Deserialize, ToSchema)]
+/// Chunk download object information
 pub struct ChunkDownloadObject {
     pub sub_oid: String,
     pub offset: i64,
     pub size: i64,
     pub link: Link,
 }
 
-#[derive(Serialize, Deserialize, Debug, Default)]
+#[derive(Serialize, Deserialize, Debug, Default, PartialEq, ToSchema)]
+/// Git reference information
 pub struct Ref {
     pub name: String,
 }
 
-#[derive(Serialize, Deserialize, Debug, Default)]
+#[derive(Serialize, Deserialize, Debug, Default, ToSchema)]
+/// Request to create a lock
 pub struct LockRequest {
     pub path: String,
     #[serde(rename(serialize = "ref", deserialize = "ref"))]
     pub refs: Ref,
 }
 
-#[derive(Serialize, Deserialize)]
+#[derive(Serialize, Deserialize, ToSchema)]
+/// Response after creating a lock
 pub struct LockResponse {
     pub lock: Lock,
     pub message: String,
 }
 
-#[derive(Serialize, Deserialize, Default)]
+#[derive(Serialize, Deserialize, Default, ToSchema)]
+/// Request to unlock a file
 pub struct UnlockRequest {
     pub force: Option<bool>,
     #[serde(rename(serialize = "ref", deserialize = "ref"))]
     pub refs: Ref,
 }
 
-#[derive(Serialize, Deserialize, Debug)]
+#[derive(Serialize, Deserialize, Debug, ToSchema)]
+/// Response after unlocking a file
 pub struct UnlockResponse {
     pub lock: Lock,
     pub message: String,
 }
 
-#[derive(Serialize, Deserialize)]
+#[derive(Serialize, Deserialize, ToSchema)]
+/// List of locks
 pub struct LockList {
     pub locks: Vec<Lock>,
     pub next_cursor: String,
 }
 
-#[derive(Serialize, Deserialize, Debug, Default)]
+#[derive(Serialize, Deserialize, Debug, Default, ToSchema)]
+/// Request to verify locks
 pub struct VerifiableLockRequest {
     #[serde(rename(serialize = "ref", deserialize = "ref"))]
     pub refs: Ref,
     pub cursor: Option<String>,
     pub limit: Option<i64>,
 }
 
-#[derive(Serialize, Deserialize, Debug)]
+#[derive(Serialize, Deserialize, Debug, ToSchema)]
+/// List of verifiable locks
 pub struct VerifiableLockList {
     pub ours: Vec<Lock>,
     pub theirs: Vec<Lock>,
     pub next_cursor: String,
 }
 
-#[derive(Serialize, Deserialize, Debug)]
+#[derive(Serialize, Deserialize, Debug, ToSchema)]
+/// Query parameters for listing locks
 pub struct LockListQuery {
     #[serde(default)]
     pub path: String,
 
@@ -0,0 +1,45 @@
+# LFS API Improvement Recommendations (GitHub Official Specification Comparison)
+
+## Comparison Baseline
+- Git LFS Batch API: https://github.com/git-lfs/git-lfs/blob/main/docs/api/batch.md
+- Git LFS Locking API: https://github.com/git-lfs/git-lfs/blob/main/docs/api/locking.md
+- Git LFS Server Discovery: https://github.com/git-lfs/git-lfs/blob/main/docs/api/server-discovery.md
+
+## Issues Found and Fix Recommendations
+
+1) Error codes are too uniform, missing 4xx status codes
+- Current state: Most errors in `mono/src/api/router/lfs_router.rs` are mapped to 500.
+- Specification: Not found objects/locks should return 404; request parameter errors should return 400.
+- Completed: Added `map_lfs_error` in router layer, mapping error messages containing `Not found` / `Invalid` to 404/400.
+- Follow-up: Use explicit error types instead of strings in `ceres/src/lfs/handler.rs` to avoid string matching.
+
+2) Download endpoint Content-Type
+- Current state: Download object/chunk uses `application/vnd.git-lfs+json`.
+- Specification: Data streams should return binary stream `application/octet-stream`.
+- Completed: Changed router download response to `application/octet-stream`.
+
+3) Batch download missing 404 semantics
+- Current state: `lfs_process_batch` returns errors mapped to 500 at router layer when download objects are missing.
+- Specification: Not found objects should return `error` at object level, with overall status 200.
+- Recommendation: In `handler::lfs_process_batch`, preserve object-level `error` for missing download objects (already implemented), router maintains 200; avoid treating missing as top-level error in handler.
+
+4) Upload pre-validation insufficient
+- Current state: `lfs_upload_object` returns generic error if meta doesn't exist (router maps to 404).
+- Recommendation: Use explicit "Not found" message or error type in handler to avoid string matching; validate that `size` matches request body length (currently commented out).
+
+5) Chunk download behavior in non-split mode
+- Current state: `lfs_download_chunk` validates hash after slicing in non-split mode, returns 500 on mismatch.
+- Recommendation: Return 400 for hash mismatch; return 404 for missing chunk.
+
+6) Lock endpoint error semantics
+- Current state: Deleting non-existent lock returns 500.
+- Recommendation: `lfs_delete_lock` should return 404 for lock not found; return 403 for no permission (currently no owner validation).
+
+7) OpenAPI coverage
+- Completed: Added `utoipa::path` to all LFS routes and registered LFS schemas in `ApiDoc`.
+- Recommendation: Provide example response (stream) documentation for LFS download endpoints in future versions.
+
+## Priority
+- High: Error code semantics (404/400), download Content-Type, lock deletion 404.
+- Medium: Batch download missing objects maintain 200 + object-level error, upload size validation.
+- Low: Hash mismatch 400, permission/lock owner validation supplement.