feat: 完善后端 API OpenAPI 文档与统一错误响应 schema

server/src/app/api/v1/endpoints/reimbursements.py

@@ -6,6 +6,7 @@ from fastapi import APIRouter, Depends, HTTPException, status
 from sqlalchemy.orm import Session
 
 from app.api.deps import get_db
+from app.schemas.common import ErrorResponse
 from app.schemas.reimbursement import ReimbursementCreate, ReimbursementRead
 from app.services.reimbursement import ReimbursementService
 
@@ -13,17 +14,39 @@ router = APIRouter()
 DbSession = Annotated[Session, Depends(get_db)]
 
 
-@router.get("", response_model=list[ReimbursementRead])
+@router.get(
+    "",
+    response_model=list[ReimbursementRead],
+    summary="查询报销申请列表",
+    description="返回当前系统中的报销申请列表。",
+)
 def list_reimbursements(db: DbSession) -> list[ReimbursementRead]:
     return ReimbursementService(db).list_reimbursements()
 
 
-@router.post("", response_model=ReimbursementRead, status_code=status.HTTP_201_CREATED)
+@router.post(
+    "",
+    response_model=ReimbursementRead,
+    status_code=status.HTTP_201_CREATED,
+    summary="创建报销申请",
+    description="创建一条新的报销申请记录，初始状态为 `draft`。",
+)
 def create_reimbursement(payload: ReimbursementCreate, db: DbSession) -> ReimbursementRead:
     return ReimbursementService(db).create_reimbursement(payload)
 
 
-@router.get("/{request_id}", response_model=ReimbursementRead)
+@router.get(
+    "/{request_id}",
+    response_model=ReimbursementRead,
+    summary="读取报销申请详情",
+    description="根据报销申请主键读取单据详情。",
+    responses={
+        status.HTTP_404_NOT_FOUND: {
+            "model": ErrorResponse,
+            "description": "报销申请不存在。",
+        }
+    },
+)
 def get_reimbursement(request_id: str, db: DbSession) -> ReimbursementRead:
     request = ReimbursementService(db).get_reimbursement(request_id)
     if request is None: