Optimize arg description

Author: wu-clan

README.zh-CN.md

@@ -67,7 +67,7 @@ mvc 架构作为常规设计模式，在 python web 中也很常见，但是三
 - [x] 字典管理：维护系统内部常用固定数据或参数
 - [x] 令牌管理：系统用户在线状态检测，支持踢人下线
 - [x] 登录认证：基于后端的图形验证码后台认证登录
-- [x] 多点登录：通过用户信息一键修改多点登录支持
+- [x] 多端登录：通过用户信息一键修改多端登录支持
 - [x] OAuth20：内置自研 OAuth 2.0 登录集成
 - [x] 代码生成：后端代码自动生成，支持预览，写入及下载
 - [x] 定时任务：自动化任务，异步任务，支持函数调用

backend/app/admin/api/v1/auth/auth.py

@@ -36,7 +36,7 @@ async def user_login(
 
 
 @router.post('/token/new', summary='创建新 token')
-async def create_new_token(request: Request, response: Response) -> ResponseSchemaModel[GetNewToken]:
+async def create_new_token(request: Request) -> ResponseSchemaModel[GetNewToken]:
     data = await auth_service.new_token(request=request)
     return response_base.success(data=data)
 

backend/app/admin/api/v1/log/login_log.py

@@ -18,17 +18,17 @@
 
 @router.get(
     '',
-    summary='（模糊条件）分页获取登录日志',
+    summary='分页获取登录日志',
     dependencies=[
         DependsJwtAuth,
         DependsPagination,
     ],
 )
 async def get_pagination_login_logs(
     db: CurrentSession,
-    username: Annotated[str | None, Query()] = None,
-    status: Annotated[int | None, Query()] = None,
-    ip: Annotated[str | None, Query()] = None,
+    username: Annotated[str | None, Query(description='用户名')] = None,
+    status: Annotated[int | None, Query(description='状态')] = None,
+    ip: Annotated[str | None, Query(description='IP 地址')] = None,
 ) -> ResponseSchemaModel[PageData[GetLoginLogDetail]]:
     log_select = await login_log_service.get_select(username=username, status=status, ip=ip)
     page_data = await paging_data(db, log_select)
@@ -37,13 +37,13 @@ async def get_pagination_login_logs(
 
 @router.delete(
     '',
-    summary='（批量）删除登录日志',
+    summary='批量删除登录日志',
     dependencies=[
         Depends(RequestPermission('log:login:del')),
         DependsRBAC,
     ],
 )
-async def delete_login_log(pk: Annotated[list[int], Query(...)]) -> ResponseModel:
+async def delete_login_log(pk: Annotated[list[int], Query(..., description='登录日志 ID 列表')]) -> ResponseModel:
     count = await login_log_service.delete(pk=pk)
     if count > 0:
         return response_base.success()

backend/app/admin/api/v1/log/opera_log.py

@@ -18,17 +18,17 @@
 
 @router.get(
     '',
-    summary='（模糊条件）分页获取操作日志',
+    summary='分页获取操作日志',
     dependencies=[
         DependsJwtAuth,
         DependsPagination,
     ],
 )
 async def get_pagination_opera_logs(
     db: CurrentSession,
-    username: Annotated[str | None, Query()] = None,
-    status: Annotated[int | None, Query()] = None,
-    ip: Annotated[str | None, Query()] = None,
+    username: Annotated[str | None, Query(description='用户名')] = None,
+    status: Annotated[int | None, Query(description='状态')] = None,
+    ip: Annotated[str | None, Query(description='IP 地址')] = None,
 ) -> ResponseSchemaModel[PageData[GetOperaLogDetail]]:
     log_select = await opera_log_service.get_select(username=username, status=status, ip=ip)
     page_data = await paging_data(db, log_select)
@@ -37,13 +37,13 @@ async def get_pagination_opera_logs(
 
 @router.delete(
     '',
-    summary='（批量）删除操作日志',
+    summary='批量删除操作日志',
     dependencies=[
         Depends(RequestPermission('log:opera:del')),
         DependsRBAC,
     ],
 )
-async def delete_opera_log(pk: Annotated[list[int], Query(...)]) -> ResponseModel:
+async def delete_opera_log(pk: Annotated[list[int], Query(..., description='操作日志 ID 列表')]) -> ResponseModel:
     count = await opera_log_service.delete(pk=pk)
     if count > 0:
         return response_base.success()

backend/app/admin/api/v1/monitor/redis.py

@@ -19,5 +19,8 @@
     ],
 )
 async def get_redis_info() -> ResponseModel:
-    data = {'info': await redis_info.get_info(), 'stats': await redis_info.get_stats()}
+    data = {
+        'info': await redis_info.get_info(),
+        'stats': await redis_info.get_stats(),
+    }
     return response_base.success(data=data)

backend/app/admin/api/v1/oauth2/linux_do.py

@@ -12,34 +12,34 @@
 
 router = APIRouter()
 
-_linux_do_client = LinuxDoOAuth20(
-    admin_settings.OAUTH2_LINUX_DO_CLIENT_ID,
-    admin_settings.OAUTH2_LINUX_DO_CLIENT_SECRET,
+_linuxdo_client = LinuxDoOAuth20(
+    admin_settings.OAUTH2_LINUXDO_CLIENT_ID,
+    admin_settings.OAUTH2_LINUXDO_CLIENT_SECRET,
 )
-_linux_do_oauth2 = FastAPIOAuth20(_linux_do_client, admin_settings.OAUTH2_LINUX_DO_REDIRECT_URI)
+_linuxdo_oauth2 = FastAPIOAuth20(_linuxdo_client, admin_settings.OAUTH2_LINUXDO_REDIRECT_URI)
 
 
-@router.get('', summary='获取 Linux Do 授权链接')
-async def linux_do_auth2() -> ResponseSchemaModel[str]:
-    auth_url = await _linux_do_client.get_authorization_url(redirect_uri=admin_settings.OAUTH2_LINUX_DO_REDIRECT_URI)
+@router.get('', summary='获取 LinuxDo 授权链接')
+async def linuxdo_auth2() -> ResponseSchemaModel[str]:
+    auth_url = await _linuxdo_client.get_authorization_url(redirect_uri=admin_settings.OAUTH2_LINUXDO_REDIRECT_URI)
     return response_base.success(data=auth_url)
 
 
 @router.get(
     '/callback',
-    summary='Linux Do 授权自动重定向',
-    description='Linux Do 授权后，自动重定向到当前地址并获取用户信息，通过用户信息自动创建系统用户',
+    summary='LinuxDo 授权自动重定向',
+    description='LinuxDo 授权后，自动重定向到当前地址并获取用户信息，通过用户信息自动创建系统用户',
     dependencies=[Depends(RateLimiter(times=5, minutes=1))],
 )
-async def linux_do_login(
+async def linuxdo_login(
     request: Request,
     response: Response,
     background_tasks: BackgroundTasks,
-    oauth2: FastAPIOAuth20 = Depends(_linux_do_oauth2),
+    oauth2: FastAPIOAuth20 = Depends(_linuxdo_oauth2),
 ):
     token, _state = oauth2
     access_token = token['access_token']
-    user = await _linux_do_client.get_userinfo(access_token)
+    user = await _linuxdo_client.get_userinfo(access_token)
     data = await oauth2_service.create_with_login(
         request=request,
         response=response,

backend/app/admin/api/v1/sys/config.py

@@ -78,23 +78,23 @@ async def save_policy_config(objs: list[SaveBuiltInConfigParam]) -> ResponseMode
     return response_base.success()
 
 
-@router.get('/{pk}', summary='获取系统参数配置详情', dependencies=[DependsJwtAuth])
-async def get_config(pk: Annotated[int, Path(...)]) -> ResponseSchemaModel[GetConfigDetail]:
+@router.get('/{pk}', summary='获取配置详情', dependencies=[DependsJwtAuth])
+async def get_config(pk: Annotated[int, Path(..., description='配置 ID')]) -> ResponseSchemaModel[GetConfigDetail]:
     config = await config_service.get(pk)
     return response_base.success(data=config)
 
 
 @router.get(
     '',
-    summary='（模糊条件）分页获取所有系统参数配置',
+    summary='分页获取所有配置',
     dependencies=[
         DependsJwtAuth,
         DependsPagination,
     ],
 )
-async def get_pagination_config(
+async def get_pagination_configs(
     db: CurrentSession,
-    name: Annotated[str | None, Query()] = None,
+    name: Annotated[str | None, Query(description='配置名称')] = None,
     type: Annotated[str | None, Query()] = None,
 ) -> ResponseSchemaModel[PageData[GetConfigDetail]]:
     config_select = await config_service.get_select(name=name, type=type)
@@ -104,7 +104,7 @@ async def get_pagination_config(
 
 @router.post(
     '',
-    summary='创建系统参数配置',
+    summary='创建配置',
     dependencies=[
         Depends(RequestPermission('sys:config:add')),
         DependsRBAC,
@@ -117,13 +117,13 @@ async def create_config(obj: CreateConfigParam) -> ResponseModel:
 
 @router.put(
     '/{pk}',
-    summary='更新系统参数配置',
+    summary='更新配置',
     dependencies=[
         Depends(RequestPermission('sys:config:edit')),
         DependsRBAC,
     ],
 )
-async def update_config(pk: Annotated[int, Path(...)], obj: UpdateConfigParam) -> ResponseModel:
+async def update_config(pk: Annotated[int, Path(..., description='配置 ID')], obj: UpdateConfigParam) -> ResponseModel:
     count = await config_service.update(pk=pk, obj=obj)
     if count > 0:
         return response_base.success()
@@ -132,13 +132,13 @@ async def update_config(pk: Annotated[int, Path(...)], obj: UpdateConfigParam) -
 
 @router.delete(
     '',
-    summary='（批量）删除系统参数配置',
+    summary='批量删除配置',
     dependencies=[
         Depends(RequestPermission('sys:config:del')),
         DependsRBAC,
     ],
 )
-async def delete_config(pk: Annotated[list[int], Query(...)]) -> ResponseModel:
+async def delete_config(pk: Annotated[list[int], Query(..., description='配置 ID 列表')]) -> ResponseModel:
     count = await config_service.delete(pk=pk)
     if count > 0:
         return response_base.success()

backend/app/admin/api/v1/sys/data_rule.py

@@ -23,33 +23,37 @@ async def get_data_rule_models() -> ResponseSchemaModel[list[str]]:
 
 
 @router.get('/model/{model}/columns', summary='获取支持过滤的数据库模型列', dependencies=[DependsJwtAuth])
-async def get_data_rule_model_columns(model: Annotated[str, Path()]) -> ResponseSchemaModel[list[str]]:
+async def get_data_rule_model_columns(
+    model: Annotated[str, Path(description='模型名称')],
+) -> ResponseSchemaModel[list[str]]:
     models = await data_rule_service.get_columns(model=model)
     return response_base.success(data=models)
 
 
 @router.get('/all', summary='获取所有数据规则', dependencies=[DependsJwtAuth])
-async def get_all_data_rule() -> ResponseSchemaModel[list[GetDataRuleDetail]]:
+async def get_all_data_rules() -> ResponseSchemaModel[list[GetDataRuleDetail]]:
     data = await data_rule_service.get_all()
     return response_base.success(data=data)
 
 
 @router.get('/{pk}', summary='获取数据权限规则详情', dependencies=[DependsJwtAuth])
-async def get_data_rule(pk: Annotated[int, Path(...)]) -> ResponseSchemaModel[GetDataRuleDetail]:
+async def get_data_rule(
+    pk: Annotated[int, Path(..., description='数据规则 ID')],
+) -> ResponseSchemaModel[GetDataRuleDetail]:
     data = await data_rule_service.get(pk=pk)
     return response_base.success(data=data)
 
 
 @router.get(
     '',
-    summary='（模糊条件）分页获取所有数据权限规则',
+    summary='分页获取所有数据权限规则',
     dependencies=[
         DependsJwtAuth,
         DependsPagination,
     ],
 )
-async def get_pagination_data_rule(
-    db: CurrentSession, name: Annotated[str | None, Query()] = None
+async def get_pagination_data_rules(
+    db: CurrentSession, name: Annotated[str | None, Query(description='规则名称')] = None
 ) -> ResponseSchemaModel[PageData[GetDataRuleDetail]]:
     data_rule_select = await data_rule_service.get_select(name=name)
     page_data = await paging_data(db, data_rule_select)
@@ -77,7 +81,9 @@ async def create_data_rule(obj: CreateDataRuleParam) -> ResponseModel:
         DependsRBAC,
     ],
 )
-async def update_data_rule(pk: Annotated[int, Path(...)], obj: UpdateDataRuleParam) -> ResponseModel:
+async def update_data_rule(
+    pk: Annotated[int, Path(..., description='数据规则 ID')], obj: UpdateDataRuleParam
+) -> ResponseModel:
     count = await data_rule_service.update(pk=pk, obj=obj)
     if count > 0:
         return response_base.success()
@@ -86,13 +92,15 @@ async def update_data_rule(pk: Annotated[int, Path(...)], obj: UpdateDataRulePar
 
 @router.delete(
     '',
-    summary='（批量）删除数据权限规则',
+    summary='批量删除数据权限规则',
     dependencies=[
         Depends(RequestPermission('data:rule:del')),
         DependsRBAC,
     ],
 )
-async def delete_data_rule(request: Request, pk: Annotated[list[int], Query(...)]) -> ResponseModel:
+async def delete_data_rule(
+    request: Request, pk: Annotated[list[int], Query(..., description='数据规则 ID 列表')]
+) -> ResponseModel:
     count = await data_rule_service.delete(request=request, pk=pk)
     if count > 0:
         return response_base.success()

backend/app/admin/api/v1/sys/dept.py

@@ -15,17 +15,17 @@
 
 
 @router.get('/{pk}', summary='获取部门详情', dependencies=[DependsJwtAuth])
-async def get_dept(pk: Annotated[int, Path(...)]) -> ResponseSchemaModel[GetDeptDetail]:
+async def get_dept(pk: Annotated[int, Path(..., description='部门 ID')]) -> ResponseSchemaModel[GetDeptDetail]:
     data = await dept_service.get(pk=pk)
     return response_base.success(data=data)
 
 
 @router.get('', summary='获取所有部门展示树', dependencies=[DependsJwtAuth])
 async def get_all_depts(
-    name: Annotated[str | None, Query()] = None,
-    leader: Annotated[str | None, Query()] = None,
-    phone: Annotated[str | None, Query()] = None,
-    status: Annotated[int | None, Query()] = None,
+    name: Annotated[str | None, Query(description='部门名称')] = None,
+    leader: Annotated[str | None, Query(description='部门负责人')] = None,
+    phone: Annotated[str | None, Query(description='联系电话')] = None,
+    status: Annotated[int | None, Query(description='状态')] = None,
 ) -> ResponseSchemaModel[list[dict[str, Any]]]:
     dept = await dept_service.get_dept_tree(name=name, leader=leader, phone=phone, status=status)
     return response_base.success(data=dept)
@@ -52,7 +52,7 @@ async def create_dept(obj: CreateDeptParam) -> ResponseModel:
         DependsRBAC,
     ],
 )
-async def update_dept(pk: Annotated[int, Path(...)], obj: UpdateDeptParam) -> ResponseModel:
+async def update_dept(pk: Annotated[int, Path(..., description='部门 ID')], obj: UpdateDeptParam) -> ResponseModel:
     count = await dept_service.update(pk=pk, obj=obj)
     if count > 0:
         return response_base.success()
@@ -67,7 +67,7 @@ async def update_dept(pk: Annotated[int, Path(...)], obj: UpdateDeptParam) -> Re
         DependsRBAC,
     ],
 )
-async def delete_dept(request: Request, pk: Annotated[int, Path(...)]) -> ResponseModel:
+async def delete_dept(request: Request, pk: Annotated[int, Path(..., description='部门 ID')]) -> ResponseModel:
     count = await dept_service.delete(request=request, pk=pk)
     if count > 0:
         return response_base.success()

backend/app/admin/api/v1/sys/dict_data.py

@@ -22,24 +22,26 @@
 
 
 @router.get('/{pk}', summary='获取字典详情', dependencies=[DependsJwtAuth])
-async def get_dict_data(pk: Annotated[int, Path(...)]) -> ResponseSchemaModel[GetDictDataWithRelation]:
+async def get_dict_data(
+    pk: Annotated[int, Path(..., description='字典数据 ID')],
+) -> ResponseSchemaModel[GetDictDataWithRelation]:
     data = await dict_data_service.get(pk=pk)
     return response_base.success(data=data)
 
 
 @router.get(
     '',
-    summary='（模糊条件）分页获取所有字典',
+    summary='分页获取所有字典',
     dependencies=[
         DependsJwtAuth,
         DependsPagination,
     ],
 )
 async def get_pagination_dict_datas(
     db: CurrentSession,
-    label: Annotated[str | None, Query()] = None,
-    value: Annotated[str | None, Query()] = None,
-    status: Annotated[int | None, Query()] = None,
+    label: Annotated[str | None, Query(description='字典数据标签')] = None,
+    value: Annotated[str | None, Query(description='字典数据键值')] = None,
+    status: Annotated[int | None, Query(description='状态')] = None,
 ) -> ResponseSchemaModel[PageData[GetDictDataDetail]]:
     dict_data_select = await dict_data_service.get_select(label=label, value=value, status=status)
     page_data = await paging_data(db, dict_data_select)
@@ -67,7 +69,9 @@ async def create_dict_data(obj: CreateDictDataParam) -> ResponseModel:
         DependsRBAC,
     ],
 )
-async def update_dict_data(pk: Annotated[int, Path(...)], obj: UpdateDictDataParam) -> ResponseModel:
+async def update_dict_data(
+    pk: Annotated[int, Path(..., description='字典数据 ID')], obj: UpdateDictDataParam
+) -> ResponseModel:
     count = await dict_data_service.update(pk=pk, obj=obj)
     if count > 0:
         return response_base.success()
@@ -76,13 +80,13 @@ async def update_dict_data(pk: Annotated[int, Path(...)], obj: UpdateDictDataPar
 
 @router.delete(
     '',
-    summary='（批量）删除字典',
+    summary='批量删除字典',
     dependencies=[
         Depends(RequestPermission('sys:dict:data:del')),
         DependsRBAC,
     ],
 )
-async def delete_dict_data(pk: Annotated[list[int], Query(...)]) -> ResponseModel:
+async def delete_dict_data(pk: Annotated[list[int], Query(..., description='字典数据 ID 列表')]) -> ResponseModel:
     count = await dict_data_service.delete(pk=pk)
     if count > 0:
         return response_base.success()