docs: 为已有的路由编写完整名称和文档

src/nyahome/router/aii_router.py

@@ -22,18 +22,37 @@ from .response_model import ReturnDto
 aii_router = APIRouter(tags=["Aii"], prefix="/aii")
 
 
-@aii_router.get("/model/")
+@aii_router.get("/model/", name="获取模型列表")
 async def get_all_model(session: Annotated[Session, Depends(get_session)]) -> ReturnDto:
+    """
+    获取 AI 模型列表。
+    此接口无需用户登录即可访问。
+
+    Returns:
+        被 ReturnDto 包裹的 AiiModel 列表
+    """
     final_model_list = apply_get_models(session)
     return ReturnDto(result=final_model_list)
 
 
-@aii_router.post("/model/")
+@aii_router.post("/model/", name="添加模型")
 async def add_model(
     model: AiiModelPublic,
     user: Annotated[ModelUser, Depends(verify_token)],
     session: Annotated[Session, Depends(get_session)],
 ) -> ReturnDto:
+    """
+    添加新的 AI 模型。需要基于已添加的模型提供商。
+    此接口需要管理员访问。
+    添加模型时不会进行可用性检查，因此 WebUI 在前端实现了检查按钮。此端点不会负责检查。
+
+    Raises:
+        HTTPException: 401 用户无权限管理模型（未登录或非管理员）
+        HTTPException: 404 模型提供商不存在
+
+    Returns:
+        被 ReturnDto 包裹的、添加的 AiiModel
+    """
     if not user.is_admin:
         raise HTTPException(status_code=401, detail="用户无权限管理模型。") from None
 
@@ -53,18 +72,36 @@ async def add_model(
     return ReturnDto(result=z_aii_model(am))
 
 
-@aii_router.get("/provider/")
+@aii_router.get("/provider/", name="获取提供商列表")
 async def get_all_provider(session: Annotated[Session, Depends(get_session)]) -> ReturnDto:
+    """
+    获取 AI 模型提供商列表。
+    此接口无需用户登录即可访问。
+
+    Returns:
+        被 ReturnDto 包裹的 AiiProvider 列表
+    """
     aii_providers = session.exec(select(AiiProvider)).all()
     return ReturnDto(result=[z_aii_provider(ap) for ap in aii_providers])
 
 
-@aii_router.post("/provider/")
+@aii_router.post("/provider/", name="添加提供商")
 async def add_provider(
     provider: AiiProviderPublic,
     user: Annotated[ModelUser, Depends(verify_token)],
     session: Annotated[Session, Depends(get_session)],
 ) -> ReturnDto:
+    """
+    添加新的 AI 模型提供商。
+    此接口需要管理员才能访问。
+    添加提供商时不会进行可用性检查，因此 WebUI 在前端实现了检查按钮。此端点不会负责检查。
+
+    Raises:
+        HTTPException: 401 表示用户未登录或非管理员。
+
+    Returns:
+        被 ReturnDto 包裹的、添加的 AiiProvider
+    """
     if not user.is_admin:
         raise HTTPException(status_code=401, detail="用户无权限管理模型。") from None
     ap = AiiProvider(name=provider.name, base_url=provider.base_url, api_key=provider.api_key)
@@ -74,10 +111,20 @@ async def add_provider(
     return ReturnDto(result=z_aii_provider(ap))
 
 
-@aii_router.get("/provider/{id_}/remote/models/")
+@aii_router.get("/provider/{id_}/remote/models/", name="获取提供商远端模型")
 async def get_provider_remote_models(
     id_: int, user: Annotated[ModelUser, Depends(verify_token)], session: Annotated[Session, Depends(get_session)]
 ) -> ReturnDto:
+    """
+    查看指定模型提供商提供的远端模型列表。并非添加到 NyaHome 的模型列表。
+    此接口需要管理员才能访问。
+
+    Raises:
+        HTTPException: 401 表示用户未登录或非管理员。
+
+    Returns:
+        被 ReturnDto 包裹的、模型名称字符串列表
+    """
     if not user.is_admin:
         raise HTTPException(status_code=401, detail="用户无权限管理模型。") from None
     try:
@@ -89,16 +136,12 @@ async def get_provider_remote_models(
     return ReturnDto(result=[m["id"] for m in models])
 
 
-@aii_router.get("/provider/{id_}/remote/model/{model_name}/")
+@aii_router.get("/provider/{id_}/remote/model/{model_name}/", name="检查指定远端模型可用性")
 async def check_remote_provider_model(
     id_: int, model_name: str, session: Annotated[Session, Depends(get_session)]
 ) -> ReturnDto:
     """
-    检测指定提供商的指定名称模型是否可用。
-    Args:
-        id_: 模型提供商 ID。
-        model_name: 模型名称。
-        session: 数据库连接对象。
+    检测指定提供商的指定名称远端模型是否可用。
 
     Raises:
         HTTPException: 404 表明提供商 ID 未找到。
@@ -113,8 +156,14 @@ async def check_remote_provider_model(
     return ReturnDto(result=await s_check_remote_model(model_name, ap.base_url, ap.api_key))
 
 
-@aii_router.post("/remote/provider/check/")
+@aii_router.post("/remote/provider/check/", name="检查指定提供商可用性")
 async def check_remote_provider(provider: AiiProviderPublic) -> ReturnDto:
+    """
+    检查指定提供商是否可用。会返回提供商提供的模型数量作为测试。
+
+    Returns:
+        ReturnDto，其中 success 字段为布尔值，表明可用状态；如果为真，result 字段是整型模型数量。
+    """
     try:
         count = len(await s_list_remote_provider_models(provider.base_url, provider.api_key))
         return ReturnDto(result=count)