feat: Add Api Docs

XiaJunjie2020 · XiaJunjie2020 · commit 8c8dbcda4e27 · 2025-12-11T16:30:41.000+08:00
diff --git a/backend/apps/datasource/api/datasource.py b/backend/apps/datasource/api/datasource.py
@@ -21,7 +21,8 @@
     check_status_by_id, sync_single_fields
 from ..crud.field import get_fields_by_table_id
 from ..crud.table import get_tables_by_ds_id
-from ..models.datasource import CoreDatasource, CreateDatasource, TableObj, CoreTable, CoreField, FieldObj
+from ..models.datasource import CoreDatasource, CreateDatasource, TableObj, CoreTable, CoreField, FieldObj, \
+    TableSchemaResponse, ColumnSchemaResponse, PreviewResponse
 
 router = APIRouter(tags=["Datasource"], prefix="/datasource")
 path = settings.EXCEL_PATH
@@ -45,57 +46,59 @@ async def get_datasource(session: SessionDep, id: int = Path(..., description=f"
     return get_ds(session, id)
 
 
-@router.post("/check")
+@router.post("/check", response_model=bool, summary=f"{PLACEHOLDER_PREFIX}ds_check")
 async def check(session: SessionDep, trans: Trans, ds: CoreDatasource):
     def inner():
         return check_status(session, trans, ds, True)
 
     return await asyncio.to_thread(inner)
 
 
-@router.get("/check/{ds_id}")
-async def check_by_id(session: SessionDep, trans: Trans, ds_id: int):
+@router.get("/check/{ds_id}", response_model=bool, summary=f"{PLACEHOLDER_PREFIX}ds_check")
+async def check_by_id(session: SessionDep, trans: Trans,
+                      ds_id: int = Path(..., description=f"{PLACEHOLDER_PREFIX}ds_id")):
     def inner():
         return check_status_by_id(session, trans, ds_id, True)
 
     return await asyncio.to_thread(inner)
 
 
-@router.post("/add", response_model=CoreDatasource)
+@router.post("/add", response_model=CoreDatasource, summary=f"{PLACEHOLDER_PREFIX}ds_add")
 async def add(session: SessionDep, trans: Trans, user: CurrentUser, ds: CreateDatasource):
     def inner():
         return create_ds(session, trans, user, ds)
 
     return await asyncio.to_thread(inner)
 
 
-@router.post("/chooseTables/{id}")
-async def choose_tables(session: SessionDep, trans: Trans, id: int, tables: List[CoreTable]):
+@router.post("/chooseTables/{id}", response_model=None, summary=f"{PLACEHOLDER_PREFIX}ds_choose_tables")
+async def choose_tables(session: SessionDep, trans: Trans, tables: List[CoreTable],
+                        id: int = Path(..., description=f"{PLACEHOLDER_PREFIX}ds_id")):
     def inner():
         chooseTables(session, trans, id, tables)
 
     await asyncio.to_thread(inner)
 
 
-@router.post("/update", response_model=CoreDatasource)
+@router.post("/update", response_model=CoreDatasource, summary=f"{PLACEHOLDER_PREFIX}ds_update")
 async def update(session: SessionDep, trans: Trans, user: CurrentUser, ds: CoreDatasource):
     def inner():
         return update_ds(session, trans, user, ds)
 
     return await asyncio.to_thread(inner)
 
 
-@router.post("/delete/{id}", response_model=CoreDatasource)
-async def delete(session: SessionDep, id: int):
+@router.post("/delete/{id}", response_model=None, summary=f"{PLACEHOLDER_PREFIX}ds_delete")
+async def delete(session: SessionDep, id: int = Path(..., description=f"{PLACEHOLDER_PREFIX}ds_id")):
     return delete_ds(session, id)
 
 
-@router.post("/getTables/{id}")
-async def get_tables(session: SessionDep, id: int):
+@router.post("/getTables/{id}", response_model=List[TableSchemaResponse], summary=f"{PLACEHOLDER_PREFIX}ds_get_tables")
+async def get_tables(session: SessionDep, id: int = Path(..., description=f"{PLACEHOLDER_PREFIX}ds_id")):
     return getTables(session, id)
 
 
-@router.post("/getTablesByConf")
+@router.post("/getTablesByConf", response_model=List[TableSchemaResponse], summary=f"{PLACEHOLDER_PREFIX}ds_get_tables")
 async def get_tables_by_conf(session: SessionDep, trans: Trans, ds: CoreDatasource):
     try:
         def inner():
@@ -113,7 +116,7 @@ def inner():
             raise HTTPException(status_code=500, detail=f'Get table Failed: {e.args}')
 
 
-@router.post("/getSchemaByConf")
+@router.post("/getSchemaByConf", response_model=List[str], summary=f"{PLACEHOLDER_PREFIX}ds_get_schema")
 async def get_schema_by_conf(session: SessionDep, trans: Trans, ds: CoreDatasource):
     try:
         def inner():
@@ -131,13 +134,16 @@ def inner():
             raise HTTPException(status_code=500, detail=f'Get table Failed: {e.args}')
 
 
-@router.post("/getFields/{id}/{table_name}")
-async def get_fields(session: SessionDep, id: int, table_name: str):
+@router.post("/getFields/{id}/{table_name}", response_model=List[ColumnSchemaResponse],
+             summary=f"{PLACEHOLDER_PREFIX}ds_get_fields")
+async def get_fields(session: SessionDep,
+                     id: int = Path(..., description=f"{PLACEHOLDER_PREFIX}ds_id"),
+                     table_name: str = Path(..., description=f"{PLACEHOLDER_PREFIX}ds_table_name")):
     return getFields(session, id, table_name)
 
 
-@router.post("/syncFields/{id}")
-async def sync_fields(session: SessionDep, id: int):
+@router.post("/syncFields/{id}", response_model=None, summary=f"{PLACEHOLDER_PREFIX}ds_sync_fields")
+async def sync_fields(session: SessionDep, id: int = Path(..., description=f"{PLACEHOLDER_PREFIX}ds_table_id")):
     return sync_single_fields(session, id)
 
 
@@ -149,7 +155,7 @@ class TestObj(BaseModel):
 
 
 # not used, just do test
-@router.post("/execSql/{id}")
+@router.post("/execSql/{id}", include_in_schema=False)
 async def exec_sql(session: SessionDep, id: int, obj: TestObj):
     def inner():
         data = execSql(session, id, obj.sql)
@@ -165,33 +171,35 @@ def inner():
     return await asyncio.to_thread(inner)
 
 
-@router.post("/tableList/{id}")
-async def table_list(session: SessionDep, id: int):
+@router.post("/tableList/{id}", response_model=List[CoreTable], summary=f"{PLACEHOLDER_PREFIX}ds_table_list")
+async def table_list(session: SessionDep, id: int = Path(..., description=f"{PLACEHOLDER_PREFIX}ds_id")):
     return get_tables_by_ds_id(session, id)
 
 
-@router.post("/fieldList/{id}")
-async def field_list(session: SessionDep, id: int, field: FieldObj):
+@router.post("/fieldList/{id}", response_model=List[CoreField], summary=f"{PLACEHOLDER_PREFIX}ds_field_list")
+async def field_list(session: SessionDep, field: FieldObj,
+                     id: int = Path(..., description=f"{PLACEHOLDER_PREFIX}ds_table_id")):
     return get_fields_by_table_id(session, id, field)
 
 
-@router.post("/editLocalComment")
+@router.post("/editLocalComment", include_in_schema=False)
 async def edit_local(session: SessionDep, data: TableObj):
     update_table_and_fields(session, data)
 
 
-@router.post("/editTable")
+@router.post("/editTable", response_model=None, summary=f"{PLACEHOLDER_PREFIX}ds_edit_table")
 async def edit_table(session: SessionDep, table: CoreTable):
     updateTable(session, table)
 
 
-@router.post("/editField")
+@router.post("/editField", response_model=None, summary=f"{PLACEHOLDER_PREFIX}ds_edit_field")
 async def edit_field(session: SessionDep, field: CoreField):
     updateField(session, field)
 
 
-@router.post("/previewData/{id}")
-async def preview_data(session: SessionDep, trans: Trans, current_user: CurrentUser, id: int, data: TableObj):
+@router.post("/previewData/{id}", response_model=PreviewResponse, summary=f"{PLACEHOLDER_PREFIX}ds_preview_data")
+async def preview_data(session: SessionDep, trans: Trans, current_user: CurrentUser, data: TableObj,
+                       id: int = Path(..., description=f"{PLACEHOLDER_PREFIX}ds_id")):
     def inner():
         try:
             return preview(session, current_user, id, data)
@@ -207,7 +215,7 @@ def inner():
 
 
 # not used
-@router.post("/fieldEnum/{id}")
+@router.post("/fieldEnum/{id}", include_in_schema=False)
 async def field_enum(session: SessionDep, id: int):
     def inner():
         return fieldEnum(session, id)
@@ -279,8 +287,8 @@ def inner():
 #     return await asyncio.to_thread(inner)
 
 
-@router.post("/uploadExcel")
-async def upload_excel(session: SessionDep, file: UploadFile = File(...)):
+@router.post("/uploadExcel", response_model=None, summary=f"{PLACEHOLDER_PREFIX}ds_upload_excel")
+async def upload_excel(session: SessionDep, file: UploadFile = File(..., description=f"{PLACEHOLDER_PREFIX}ds_excel")):
     ALLOWED_EXTENSIONS = {"xlsx", "xls", "csv"}
     if not file.filename.lower().endswith(tuple(ALLOWED_EXTENSIONS)):
         raise HTTPException(400, "Only support .xlsx/.xls/.csv")
diff --git a/backend/apps/datasource/models/datasource.py b/backend/apps/datasource/models/datasource.py
@@ -75,17 +75,18 @@ class CreateDatasource(BaseModel):
     tables: List[CoreTable] = []
     recommended_config: int = 1
 
+
 class RecommendedProblemResponse:
-    def __init__(self, datasource_id,recommended_config,questions):
+    def __init__(self, datasource_id, recommended_config, questions):
         self.datasource_id = datasource_id
         self.recommended_config = recommended_config
         self.questions = questions
+
     datasource_id: int = None
     recommended_config: int = None
     questions: str = None
 
 
-
 class RecommendedProblemBase(BaseModel):
     datasource_id: int = None
     recommended_config: int = None
@@ -146,6 +147,11 @@ def __init__(self, attr1, attr2):
     tableComment: str
 
 
+class TableSchemaResponse(BaseModel):
+    tableName: str = None
+    tableComment: str = None
+
+
 class ColumnSchema:
     def __init__(self, attr1, attr2, attr3):
         self.fieldName = attr1
@@ -157,6 +163,12 @@ def __init__(self, attr1, attr2, attr3):
     fieldComment: str
 
 
+class ColumnSchemaResponse(BaseModel):
+    fieldName: str
+    fieldType: str
+    fieldComment: str
+
+
 class TableAndFields:
     def __init__(self, schema, table, fields):
         self.schema = schema
@@ -170,3 +182,8 @@ def __init__(self, schema, table, fields):
 
 class FieldObj(BaseModel):
     fieldName: str | None
+
+class PreviewResponse(BaseModel):
+    fields:List = []
+    data:List = []
+    sql:str = ''
diff --git a/backend/apps/swagger/locales/en.json b/backend/apps/swagger/locales/en.json
@@ -3,5 +3,23 @@
   "ds_list": "Datasource list",
   "ds_list_description": "Retrieve all data sources under the current workspace",
   "ds_get": "Get Datasource",
-  "ds_id": "Datasource ID"
+  "ds_id": "Datasource ID",
+  "ds_check": "Datasource status check",
+  "ds_add": "Create Datasource",
+  "ds_choose_tables": "Select Tables",
+  "ds_update": "Edit Datasource",
+  "ds_delete": "Delete Datasource",
+  "ds_get_tables": "Query Table info from database",
+  "ds_get_schema": "Query Schema from database",
+  "ds_get_fields": "Query Fields from database",
+  "ds_sync_fields": "Sync Fields",
+  "ds_table_id": "Table ID",
+  "ds_table_name": "Table Name",
+  "ds_table_list": "Get Table List",
+  "ds_field_list": "Get Field List",
+  "ds_edit_table": "Edit Table Info",
+  "ds_edit_field": "Edit Field Info",
+  "ds_preview_data": "Preview Data",
+  "ds_upload_excel": "Upload Excel",
+  "ds_excel": "File"
 }
diff --git a/backend/apps/swagger/locales/zh.json b/backend/apps/swagger/locales/zh.json
@@ -3,5 +3,23 @@
   "ds_list": "数据源列表",
   "ds_list_description": "获取当前工作空间下所有数据源",
   "ds_get": "获取数据源",
-  "ds_id": "数据源 ID"
+  "ds_id": "数据源 ID",
+  "ds_check": "数据源状态校验",
+  "ds_add": "创建数据源",
+  "ds_choose_tables": "选择数据表",
+  "ds_update": "编辑数据源",
+  "ds_delete": "删除数据源",
+  "ds_get_tables": "获取数据库的表信息",
+  "ds_get_schema": "获取数据库Schema",
+  "ds_get_fields": "获取数据库表字段",
+  "ds_sync_fields": "同步表字段",
+  "ds_table_id": "表 ID",
+  "ds_table_name": "表名",
+  "ds_table_list": "获取表列表",
+  "ds_field_list": "获取字段列表",
+  "ds_edit_table": "编辑表信息",
+  "ds_edit_field": "编辑字段信息",
+  "ds_preview_data": "预览数据",
+  "ds_upload_excel": "上传Excel",
+  "ds_excel": "文件"
 }
