优化API文档，添加参数描述和示例

app/api/v1/endpoints/components/options.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Request
+from fastapi import APIRouter, Request, Query, Path, Body
 from typing import Any, List, Dict, Union
 from app.services.tjnetwork import (
     Any,
@@ -19,57 +19,119 @@ from app.services.tjnetwork import (
 
 router = APIRouter()
 
-@router.get("/gettimeschema")
-async def fastapi_get_time_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/gettimeschema", summary="获取时间选项架构", description="获取网络中时间选项的架构定义")
+async def fastapi_get_time_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[str, Any]]:
+    """获取时间选项架构。
+    
+    返回指定网络中时间相关选项的属性架构定义。
+    """
     return get_time_schema(network)
 
-@router.get("/gettimeproperties/")
-async def fastapi_get_time_properties(network: str) -> dict[str, Any]:
+@router.get("/gettimeproperties/", summary="获取时间选项属性", description="获取指定网络中的时间选项属性信息")
+async def fastapi_get_time_properties(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, Any]:
+    """获取时间选项属性。
+    
+    返回指定网络中的时间相关选项属性。
+    """
     return get_time(network)
 
-@router.post("/settimeproperties/", response_model=None)
-async def fastapi_set_time_properties(network: str, req: Request) -> ChangeSet:
+@router.post("/settimeproperties/", response_model=None, summary="设置时间选项属性", description="更新指定网络中的时间选项属性")
+async def fastapi_set_time_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = Body(...)
+) -> ChangeSet:
+    """设置时间选项属性。
+    
+    更新指定网络中的时间相关选项属性值。
+    """
     props = await req.json()
     return set_time(network, ChangeSet(props))
 
-@router.get("/getenergyschema/")
-async def fastapi_get_energy_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/getenergyschema/", summary="获取能耗选项架构", description="获取网络中能耗选项的架构定义")
+async def fastapi_get_energy_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[str, Any]]:
+    """获取能耗选项架构。
+    
+    返回指定网络中能耗相关选项的属性架构定义。
+    """
     return get_energy_schema(network)
 
-@router.get("/getenergyproperties/")
-async def fastapi_get_energy_properties(network: str) -> dict[str, Any]:
+@router.get("/getenergyproperties/", summary="获取能耗选项属性", description="获取指定网络中的能耗选项属性信息")
+async def fastapi_get_energy_properties(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, Any]:
+    """获取能耗选项属性。
+    
+    返回指定网络中的能耗相关选项属性。
+    """
     return get_energy(network)
 
-@router.post("/setenergyproperties/", response_model=None)
-async def fastapi_set_energy_properties(network: str, req: Request) -> ChangeSet:
+@router.post("/setenergyproperties/", response_model=None, summary="设置能耗选项属性", description="更新指定网络中的能耗选项属性")
+async def fastapi_set_energy_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = Body(...)
+) -> ChangeSet:
+    """设置能耗选项属性。
+    
+    更新指定网络中的能耗相关选项属性值。
+    """
     props = await req.json()
     return set_energy(network, ChangeSet(props))
 
-@router.get("/getpumpenergyschema/")
-async def fastapi_get_pump_energy_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/getpumpenergyschema/", summary="获取泵能耗选项架构", description="获取网络中泵能耗选项的架构定义")
+async def fastapi_get_pump_energy_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[str, Any]]:
+    """获取泵能耗选项架构。
+    
+    返回指定网络中泵能耗相关选项的属性架构定义。
+    """
     return get_pump_energy_schema(network)
 
-@router.get("/getpumpenergyproperties//")
-async def fastapi_get_pump_energy_proeprties(network: str, pump: str) -> dict[str, Any]:
+@router.get("/getpumpenergyproperties//", summary="获取泵能耗属性", description="获取指定泵的能耗属性信息")
+async def fastapi_get_pump_energy_proeprties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pump: str = Query(..., description="泵ID")
+) -> dict[str, Any]:
+    """获取泵能耗属性。
+    
+    返回指定泵的能耗相关属性。
+    """
     return get_pump_energy(network, pump)
 
-@router.get("/setpumpenergyproperties//", response_model=None)
+@router.get("/setpumpenergyproperties//", response_model=None, summary="设置泵能耗属性", description="更新指定泵的能耗属性")
 async def fastapi_set_pump_energy_properties(
-    network: str, pump: str, req: Request
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    pump: str = Query(..., description="泵ID"),
+    req: Request = Body(...)
 ) -> ChangeSet:
+    """设置泵能耗属性。
+    
+    更新指定泵的能耗相关属性值。
+    """
     props = await req.json()
     ps = {"id": pump} | props
     return set_pump_energy(network, ChangeSet(ps))
 
-@router.get("/getoptionschema/")
-async def fastapi_get_option_schema(network: str) -> dict[str, dict[str, Any]]:
+@router.get("/getoptionschema/", summary="获取选项架构", description="获取网络中选项对象的架构定义")
+async def fastapi_get_option_schema(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, dict[str, Any]]:
+    """获取选项架构。
+    
+    返回指定网络中选项对象的属性架构定义。
+    """
     return get_option_v3_schema(network)
 
-@router.get("/getoptionproperties/")
-async def fastapi_get_option_properties(network: str) -> dict[str, Any]:
+@router.get("/getoptionproperties/", summary="获取选项属性", description="获取指定网络中的选项属性信息")
+async def fastapi_get_option_properties(network: str = Query(..., description="管网名称（或数据库名称）")) -> dict[str, Any]:
+    """获取选项属性。
+    
+    返回指定网络中的选项对象属性信息。
+    """
     return get_option_v3(network)
 
-@router.post("/setoptionproperties/", response_model=None)
-async def fastapi_set_option_properties(network: str, req: Request) -> ChangeSet:
+@router.post("/setoptionproperties/", response_model=None, summary="设置选项属性", description="更新指定网络中的选项属性")
+async def fastapi_set_option_properties(
+    network: str = Query(..., description="管网名称（或数据库名称）"),
+    req: Request = Body(...)
+) -> ChangeSet:
+    """设置选项属性。
+    
+    更新指定网络中的选项属性值。
+    """
     props = await req.json()
     return set_option_v3(network, ChangeSet(props))