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

2026-03-13 15:17:06 +08:00
parent 9a8d851275
commit b513d05611
38 changed files with 5846 additions and 1224 deletions
@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends, HTTPException, Query, Path, Body
 from typing import List
 from datetime import datetime
 from psycopg import AsyncConnection
@@ -9,37 +9,84 @@ from .dependencies import get_timescale_connection
 router = APIRouter()


-@router.post("/scheme/links/batch", status_code=201)
+@router.post("/scheme/links/batch", status_code=201, summary="批量插入方案管道数据",
+             tags=["时间序列-方案数据"])
 async def insert_scheme_links(
-    data: List[dict], conn: AsyncConnection = Depends(get_timescale_connection)
+    data: List[dict] = Body(..., description="方案管道数据列表"),
+    conn: AsyncConnection = Depends(get_timescale_connection)
 ):
+    """
+    批量插入方案管道数据
+    
+    将特定方案的管道模拟数据批量插入时间序列数据库。
+    
+    Args:
+        data: 方案管道数据列表
+        
+    Returns:
+        插入成功的记录数
+    """
    await SchemeRepository.insert_links_batch(conn, data)
    return {"message": f"Inserted {len(data)} records"}


-@router.get("/scheme/links")
+@router.get("/scheme/links", summary="查询方案管道数据", tags=["时间序列-方案数据"])
 async def get_scheme_links(
-    scheme_type: str,
-    scheme_name: str,
-    start_time: datetime,
-    end_time: datetime,
+    scheme_type: str = Query(..., description="方案类型"),
+    scheme_name: str = Query(..., description="方案名称"),
+    start_time: datetime = Query(..., description="查询开始时间"),
+    end_time: datetime = Query(..., description="查询结束时间"),
    conn: AsyncConnection = Depends(get_timescale_connection),
 ):
+    """
+    查询指定方案和时间范围内的管道数据
+    
+    根据方案和时间范围查询管道的模拟值。
+    
+    Args:
+        scheme_type: 方案类型
+        scheme_name: 方案名称
+        start_time: 查询开始时间
+        end_time: 查询结束时间
+        
+    Returns:
+        方案管道数据列表
+    """
    return await SchemeRepository.get_links_by_scheme_and_time_range(
        conn, scheme_type, scheme_name, start_time, end_time
    )


-@router.get("/scheme/links/{link_id}/field")
+@router.get("/scheme/links/{link_id}/field", summary="查询方案管道字段数据",
+            tags=["时间序列-方案数据"])
 async def get_scheme_link_field(
-    scheme_type: str,
-    scheme_name: str,
-    link_id: str,
-    start_time: datetime,
-    end_time: datetime,
-    field: str,
+    link_id: str = Path(..., description="管道ID"),
+    scheme_type: str = Query(..., description="方案类型"),
+    scheme_name: str = Query(..., description="方案名称"),
+    start_time: datetime = Query(..., description="查询开始时间"),
+    end_time: datetime = Query(..., description="查询结束时间"),
+    field: str = Query(..., description="要查询的字段名称"),
    conn: AsyncConnection = Depends(get_timescale_connection),
 ):
+    """
+    查询指定方案管道的特定字段数据
+    
+    查询特定方案中指定管道在时间范围内的特定字段值。
+    
+    Args:
+        link_id: 管道ID
+        scheme_type: 方案类型
+        scheme_name: 方案名称
+        start_time: 查询开始时间
+        end_time: 查询结束时间
+        field: 字段名称
+        
+    Returns:
+        字段数据列表
+        
+    Raises:
+        HTTPException: 当查询参数无效时返回400错误
+    """
    try:
        return await SchemeRepository.get_link_field_by_scheme_and_time_range(
            conn, scheme_type, scheme_name, start_time, end_time, link_id, field
@@ -48,16 +95,36 @@ async def get_scheme_link_field(
        raise HTTPException(status_code=400, detail=str(e))


-@router.patch("/scheme/links/{link_id}/field")
+@router.patch("/scheme/links/{link_id}/field", summary="更新方案管道字段",
+              tags=["时间序列-方案数据"])
 async def update_scheme_link_field(
-    scheme_type: str,
-    scheme_name: str,
-    link_id: str,
-    time: datetime,
-    field: str,
-    value: float,
+    link_id: str = Path(..., description="管道ID"),
+    scheme_type: str = Query(..., description="方案类型"),
+    scheme_name: str = Query(..., description="方案名称"),
+    time: datetime = Query(..., description="更新数据的时间戳"),
+    field: str = Query(..., description="要更新的字段名称"),
+    value: float = Query(..., description="更新的字段值"),
    conn: AsyncConnection = Depends(get_timescale_connection),
 ):
+    """
+    更新指定方案管道的字段值
+    
+    更新特定方案中指定管道在某个时间的字段数据。
+    
+    Args:
+        link_id: 管道ID
+        scheme_type: 方案类型
+        scheme_name: 方案名称
+        time: 数据时间戳
+        field: 字段名称
+        value: 字段新值
+        
+    Returns:
+        更新结果信息
+        
+    Raises:
+        HTTPException: 当字段不存在或更新失败时返回400错误
+    """
    try:
        await SchemeRepository.update_link_field(
            conn, time, scheme_type, scheme_name, link_id, field, value
@@ -67,38 +134,85 @@ async def update_scheme_link_field(
        raise HTTPException(status_code=400, detail=str(e))


-@router.delete("/scheme/links")
+@router.delete("/scheme/links", summary="删除方案管道数据", tags=["时间序列-方案数据"])
 async def delete_scheme_links(
-    scheme_type: str,
-    scheme_name: str,
-    start_time: datetime,
-    end_time: datetime,
+    scheme_type: str = Query(..., description="方案类型"),
+    scheme_name: str = Query(..., description="方案名称"),
+    start_time: datetime = Query(..., description="删除开始时间"),
+    end_time: datetime = Query(..., description="删除结束时间"),
    conn: AsyncConnection = Depends(get_timescale_connection),
 ):
+    """
+    删除指定方案和时间范围内的管道数据
+    
+    删除在指定方案和时间范围内的所有管道模拟数据。
+    
+    Args:
+        scheme_type: 方案类型
+        scheme_name: 方案名称
+        start_time: 删除开始时间
+        end_time: 删除结束时间
+        
+    Returns:
+        删除结果信息
+    """
    await SchemeRepository.delete_links_by_scheme_and_time_range(
        conn, scheme_type, scheme_name, start_time, end_time
    )
    return {"message": "Deleted successfully"}


-@router.post("/scheme/nodes/batch", status_code=201)
+@router.post("/scheme/nodes/batch", status_code=201, summary="批量插入方案节点数据",
+             tags=["时间序列-方案数据"])
 async def insert_scheme_nodes(
-    data: List[dict], conn: AsyncConnection = Depends(get_timescale_connection)
+    data: List[dict] = Body(..., description="方案节点数据列表"),
+    conn: AsyncConnection = Depends(get_timescale_connection)
 ):
+    """
+    批量插入方案节点数据
+    
+    将特定方案的节点模拟数据批量插入时间序列数据库。
+    
+    Args:
+        data: 方案节点数据列表
+        
+    Returns:
+        插入成功的记录数
+    """
    await SchemeRepository.insert_nodes_batch(conn, data)
    return {"message": f"Inserted {len(data)} records"}


-@router.get("/scheme/nodes/{node_id}/field")
+@router.get("/scheme/nodes/{node_id}/field", summary="查询方案节点字段数据",
+            tags=["时间序列-方案数据"])
 async def get_scheme_node_field(
-    scheme_type: str,
-    scheme_name: str,
-    node_id: str,
-    start_time: datetime,
-    end_time: datetime,
-    field: str,
+    node_id: str = Path(..., description="节点ID"),
+    scheme_type: str = Query(..., description="方案类型"),
+    scheme_name: str = Query(..., description="方案名称"),
+    start_time: datetime = Query(..., description="查询开始时间"),
+    end_time: datetime = Query(..., description="查询结束时间"),
+    field: str = Query(..., description="要查询的字段名称"),
    conn: AsyncConnection = Depends(get_timescale_connection),
 ):
+    """
+    查询指定方案节点的特定字段数据
+    
+    查询特定方案中指定节点在时间范围内的特定字段值。
+    
+    Args:
+        node_id: 节点ID
+        scheme_type: 方案类型
+        scheme_name: 方案名称
+        start_time: 查询开始时间
+        end_time: 查询结束时间
+        field: 字段名称
+        
+    Returns:
+        字段数据列表
+        
+    Raises:
+        HTTPException: 当查询参数无效时返回400错误
+    """
    try:
        return await SchemeRepository.get_node_field_by_scheme_and_time_range(
            conn, scheme_type, scheme_name, start_time, end_time, node_id, field
@@ -107,16 +221,36 @@ async def get_scheme_node_field(
        raise HTTPException(status_code=400, detail=str(e))


-@router.patch("/scheme/nodes/{node_id}/field")
+@router.patch("/scheme/nodes/{node_id}/field", summary="更新方案节点字段",
+              tags=["时间序列-方案数据"])
 async def update_scheme_node_field(
-    scheme_type: str,
-    scheme_name: str,
-    node_id: str,
-    time: datetime,
-    field: str,
-    value: float,
+    node_id: str = Path(..., description="节点ID"),
+    scheme_type: str = Query(..., description="方案类型"),
+    scheme_name: str = Query(..., description="方案名称"),
+    time: datetime = Query(..., description="更新数据的时间戳"),
+    field: str = Query(..., description="要更新的字段名称"),
+    value: float = Query(..., description="更新的字段值"),
    conn: AsyncConnection = Depends(get_timescale_connection),
 ):
+    """
+    更新指定方案节点的字段值
+    
+    更新特定方案中指定节点在某个时间的字段数据。
+    
+    Args:
+        node_id: 节点ID
+        scheme_type: 方案类型
+        scheme_name: 方案名称
+        time: 数据时间戳
+        field: 字段名称
+        value: 字段新值
+        
+    Returns:
+        更新结果信息
+        
+    Raises:
+        HTTPException: 当字段不存在或更新失败时返回400错误
+    """
    try:
        await SchemeRepository.update_node_field(
            conn, time, scheme_type, scheme_name, node_id, field, value
@@ -126,30 +260,59 @@ async def update_scheme_node_field(
        raise HTTPException(status_code=400, detail=str(e))


-@router.delete("/scheme/nodes")
+@router.delete("/scheme/nodes", summary="删除方案节点数据", tags=["时间序列-方案数据"])
 async def delete_scheme_nodes(
-    scheme_type: str,
-    scheme_name: str,
-    start_time: datetime,
-    end_time: datetime,
+    scheme_type: str = Query(..., description="方案类型"),
+    scheme_name: str = Query(..., description="方案名称"),
+    start_time: datetime = Query(..., description="删除开始时间"),
+    end_time: datetime = Query(..., description="删除结束时间"),
    conn: AsyncConnection = Depends(get_timescale_connection),
 ):
+    """
+    删除指定方案和时间范围内的节点数据
+    
+    删除在指定方案和时间范围内的所有节点模拟数据。
+    
+    Args:
+        scheme_type: 方案类型
+        scheme_name: 方案名称
+        start_time: 删除开始时间
+        end_time: 删除结束时间
+        
+    Returns:
+        删除结果信息
+    """
    await SchemeRepository.delete_nodes_by_scheme_and_time_range(
        conn, scheme_type, scheme_name, start_time, end_time
    )
    return {"message": "Deleted successfully"}


-@router.post("/scheme/simulation/store", status_code=201)
+@router.post("/scheme/simulation/store", status_code=201, summary="存储方案模拟结果",
+             tags=["时间序列-方案数据"])
 async def store_scheme_simulation_result(
-    scheme_type: str,
-    scheme_name: str,
-    node_result_list: List[dict],
-    link_result_list: List[dict],
-    result_start_time: str,
+    scheme_type: str = Query(..., description="方案类型"),
+    scheme_name: str = Query(..., description="方案名称"),
+    node_result_list: List[dict] = Body(..., description="节点模拟结果列表"),
+    link_result_list: List[dict] = Body(..., description="管道模拟结果列表"),
+    result_start_time: str = Query(..., description="模拟结果开始时间"),
    conn: AsyncConnection = Depends(get_timescale_connection),
 ):
-    """Store scheme simulation results to TimescaleDB"""
+    """
+    存储方案模拟结果到时间序列数据库
+    
+    将特定方案的节点和管道模拟计算结果批量存储到TimescaleDB数据库。
+    
+    Args:
+        scheme_type: 方案类型
+        scheme_name: 方案名称
+        node_result_list: 节点模拟结果列表
+        link_result_list: 管道模拟结果列表
+        result_start_time: 模拟结果对应的起始时间
+        
+    Returns:
+        存储结果信息
+    """
    await SchemeRepository.store_scheme_simulation_result(
        conn,
        scheme_type,
@@ -161,16 +324,34 @@ async def store_scheme_simulation_result(
    return {"message": "Scheme simulation results stored successfully"}


-@router.get("/scheme/query/by-scheme-time-property")
+@router.get("/scheme/query/by-scheme-time-property", summary="按方案、时间和属性查询数据",
+            tags=["时间序列-方案数据"])
 async def query_scheme_records_by_scheme_time_property(
-    scheme_type: str,
-    scheme_name: str,
-    query_time: str,
-    type: str,
-    property: str,
+    scheme_type: str = Query(..., description="方案类型"),
+    scheme_name: str = Query(..., description="方案名称"),
+    query_time: str = Query(..., description="查询时间"),
+    type: str = Query(..., description="元素类型，pipe（管道）或 junction（节点）"),
+    property: str = Query(..., description="要查询的属性名称"),
    conn: AsyncConnection = Depends(get_timescale_connection),
 ):
-    """Query all scheme records by scheme, time and property"""
+    """
+    按指定方案、时间和属性查询所有方案数据
+    
+    查询在特定方案和时间点，所有指定类型元素的特定属性值。
+    
+    Args:
+        scheme_type: 方案类型
+        scheme_name: 方案名称
+        query_time: 查询时间
+        type: 元素类型（pipe或junction）
+        property: 属性名称
+        
+    Returns:
+        查询结果列表
+        
+    Raises:
+        HTTPException: 当查询参数无效时返回400错误
+    """
    try:
        results = await SchemeRepository.query_all_record_by_scheme_time_property(
            conn, scheme_type, scheme_name, query_time, type, property
@@ -180,16 +361,34 @@ async def query_scheme_records_by_scheme_time_property(
        raise HTTPException(status_code=400, detail=str(e))


-@router.get("/scheme/query/by-id-time")
+@router.get("/scheme/query/by-id-time", summary="按ID和时间查询方案模拟数据",
+            tags=["时间序列-方案数据"])
 async def query_scheme_simulation_by_id_time(
-    scheme_type: str,
-    scheme_name: str,
-    id: str,
-    type: str,
-    query_time: str,
+    scheme_type: str = Query(..., description="方案类型"),
+    scheme_name: str = Query(..., description="方案名称"),
+    id: str = Query(..., description="元素ID（管道ID或节点ID）"),
+    type: str = Query(..., description="元素类型，pipe（管道）或 junction（节点）"),
+    query_time: str = Query(..., description="查询时间"),
    conn: AsyncConnection = Depends(get_timescale_connection),
 ):
-    """Query scheme simulation results by id and time"""
+    """
+    按指定ID和时间查询方案模拟结果
+    
+    查询特定方案中的元素在某一时间点的模拟数据。
+    
+    Args:
+        scheme_type: 方案类型
+        scheme_name: 方案名称
+        id: 元素ID
+        type: 元素类型（pipe或junction）
+        query_time: 查询时间
+        
+    Returns:
+        模拟结果数据
+        
+    Raises:
+        HTTPException: 当查询参数无效时返回400错误
+    """
    try:
        result = await SchemeRepository.query_scheme_simulation_result_by_id_time(
            conn, scheme_type, scheme_name, id, type, query_time