From 88df42fe5277b44f08aef03c079f447340074a20 Mon Sep 17 00:00:00 2001 From: Nick Zeng Date: Wed, 18 Mar 2026 09:13:53 +0800 Subject: [PATCH] update api doc --- .../app/Controller/Api/V1/DashboardController.php | 6 +++--- .../Controller/Api/V1/FailedMessageController.php | 4 ++-- .../app/Controller/Api/V1/MqStatusController.php | 2 +- .../Controller/Api/V1/OperationLogController.php | 4 ++-- .../app/Controller/Api/V1/RequestLogController.php | 4 ++-- backend/app/Controller/api/v1/ApiKeyController.php | 8 ++++---- .../app/Controller/api/v1/DataScopeController.php | 6 +++--- .../app/Controller/api/v1/RouteGroupController.php | 14 +++++++------- backend/app/Storage/MemoryTableStorage.php | 6 +++++- 9 files changed, 29 insertions(+), 25 deletions(-) diff --git a/backend/app/Controller/Api/V1/DashboardController.php b/backend/app/Controller/Api/V1/DashboardController.php index e3c915d..f1ae4ca 100644 --- a/backend/app/Controller/Api/V1/DashboardController.php +++ b/backend/app/Controller/Api/V1/DashboardController.php @@ -33,7 +33,7 @@ class DashboardController extends AbstractController * 概览统计 */ #[OA\Get( - path: '/api/v1/dashboard/overview', + path: '/dashboard/overview', summary: '获取概览统计', description: '返回今日/本周/本月的成功和失败同步数，以及按数据类型的本月分组统计。', security: [['bearerAuth' => []]], @@ -71,7 +71,7 @@ class DashboardController extends AbstractController * 趋势数据 */ #[OA\Get( - path: '/api/v1/dashboard/trend', + path: '/dashboard/trend', summary: '获取趋势数据', description: '返回指定时间范围内按日/周/月聚合的成功和失败同步趋势。', security: [['bearerAuth' => []]], @@ -157,7 +157,7 @@ class DashboardController extends AbstractController * 分组统计 */ #[OA\Get( - path: '/api/v1/dashboard/breakdown', + path: '/dashboard/breakdown', summary: '获取分组统计', description: '按公司/平台/店铺维度统计成功和失败同步数。', security: [['bearerAuth' => []]], diff --git a/backend/app/Controller/Api/V1/FailedMessageController.php b/backend/app/Controller/Api/V1/FailedMessageController.php index 6e81978..08044a1 100644 --- a/backend/app/Controller/Api/V1/FailedMessageController.php +++ b/backend/app/Controller/Api/V1/FailedMessageController.php @@ -69,7 +69,7 @@ class FailedMessageController extends AbstractDataController * 失败消息列表 */ #[OA\Get( - path: '/api/v1/failed-messages', + path: '/failed-messages', summary: '失败消息列表', description: '获取 Consumer 处理失败的消息列表，支持分页、按数据类型/平台/时间筛选。仅 admin 可访问。', security: [['bearerAuth' => []]], @@ -112,7 +112,7 @@ class FailedMessageController extends AbstractDataController * 失败消息详情 */ #[OA\Get( - path: '/api/v1/failed-messages/{id}', + path: '/failed-messages/{id}', summary: '失败消息详情', description: '获取失败消息详情，含完整错误堆栈和原始消息体。仅 admin 可访问。', security: [['bearerAuth' => []]], diff --git a/backend/app/Controller/Api/V1/MqStatusController.php b/backend/app/Controller/Api/V1/MqStatusController.php index b483699..2d92a4d 100644 --- a/backend/app/Controller/Api/V1/MqStatusController.php +++ b/backend/app/Controller/Api/V1/MqStatusController.php @@ -34,7 +34,7 @@ class MqStatusController extends AbstractController * 获取消息队列状态 */ #[OA\Get( - path: '/api/v1/mq/status', + path: '/mq/status', summary: '获取消息队列状态', description: '查询 RabbitMQ 各队列的消息数、消费者数和运行状态。支持按队列类型筛选。仅 admin 角色可访问。', security: [['bearerAuth' => []]], diff --git a/backend/app/Controller/Api/V1/OperationLogController.php b/backend/app/Controller/Api/V1/OperationLogController.php index 60df3b6..db51ef2 100644 --- a/backend/app/Controller/Api/V1/OperationLogController.php +++ b/backend/app/Controller/Api/V1/OperationLogController.php @@ -71,7 +71,7 @@ class OperationLogController extends AbstractDataController * 操作日志列表 */ #[OA\Get( - path: '/api/v1/logs/operations', + path: '/logs/operations', summary: '操作日志列表', description: '获取操作日志列表，支持分页、按用户/操作类型/目标类型/时间筛选。仅 admin 可访问。', security: [['bearerAuth' => []]], @@ -114,7 +114,7 @@ class OperationLogController extends AbstractDataController * 操作日志详情 */ #[OA\Get( - path: '/api/v1/logs/operations/{id}', + path: '/logs/operations/{id}', summary: '操作日志详情', description: '获取操作日志详情，含完整操作详情 JSON。仅 admin 可访问。', security: [['bearerAuth' => []]], diff --git a/backend/app/Controller/Api/V1/RequestLogController.php b/backend/app/Controller/Api/V1/RequestLogController.php index 74d8a78..2d39818 100644 --- a/backend/app/Controller/Api/V1/RequestLogController.php +++ b/backend/app/Controller/Api/V1/RequestLogController.php @@ -64,7 +64,7 @@ class RequestLogController extends AbstractDataController * 请求日志列表 */ #[OA\Get( - path: '/api/v1/logs/requests', + path: '/logs/requests', summary: '请求日志列表', description: '获取 API 请求日志列表，支持分页、按用户/方法/路径/状态码/时间筛选。仅 admin 可访问。', security: [['bearerAuth' => []]], @@ -108,7 +108,7 @@ class RequestLogController extends AbstractDataController * 请求日志详情 */ #[OA\Get( - path: '/api/v1/logs/requests/{id}', + path: '/logs/requests/{id}', summary: '请求日志详情', description: '获取请求日志详情，含完整请求体和 User-Agent。仅 admin 可访问。', security: [['bearerAuth' => []]], diff --git a/backend/app/Controller/api/v1/ApiKeyController.php b/backend/app/Controller/api/v1/ApiKeyController.php index 5d7d37e..af375cf 100644 --- a/backend/app/Controller/api/v1/ApiKeyController.php +++ b/backend/app/Controller/api/v1/ApiKeyController.php @@ -14,7 +14,7 @@ use Hyperf\HttpServer\Annotation\RequestMapping; use OpenApi\Attributes as OA; use Qbhy\HyperfAuth\AuthManager; -#[OA\Tag(name: 'ApiKeys', description: 'API Key 管理')] +#[OA\Tag(name: 'API Keys', description: 'API Key 管理')] #[Controller(prefix: "/api/v1/me/api-keys")] class ApiKeyController extends AbstractController { @@ -28,7 +28,7 @@ class ApiKeyController extends AbstractController summary: '生成 API Key', description: '生成新的 API Key，需用户已启用 api_key_enabled。明文仅在生成时返回一次', security: [['bearerAuth' => []]], - tags: ['ApiKeys'], + tags: ['API Keys'], requestBody: new OA\RequestBody( required: true, content: new OA\JsonContent( @@ -138,7 +138,7 @@ class ApiKeyController extends AbstractController summary: 'API Key 列表', description: '列出当前用户的所有 API Keys', security: [['bearerAuth' => []]], - tags: ['ApiKeys'], + tags: ['API Keys'], responses: [ new OA\Response( response: 200, @@ -192,7 +192,7 @@ class ApiKeyController extends AbstractController path: '/me/api-keys/{id}', summary: '删除 API Key', security: [['bearerAuth' => []]], - tags: ['ApiKeys'], + tags: ['API Keys'], parameters: [ new OA\Parameter(name: 'id', in: 'path', required: true, description: 'API Key ID', schema: new OA\Schema(type: 'integer')), ], diff --git a/backend/app/Controller/api/v1/DataScopeController.php b/backend/app/Controller/api/v1/DataScopeController.php index 7109bc6..d9e32ce 100644 --- a/backend/app/Controller/api/v1/DataScopeController.php +++ b/backend/app/Controller/api/v1/DataScopeController.php @@ -23,7 +23,7 @@ use Hyperf\HttpServer\Annotation\RequestMapping; use OpenApi\Attributes as OA; use Psr\Http\Message\ResponseInterface; -#[OA\Tag(name: 'DataScope', description: '用户数据范围管理')] +#[OA\Tag(name: 'Data Scope', description: '用户数据范围管理')] #[Controller(prefix: "/api/v1/users")] class DataScopeController extends AbstractController { @@ -45,7 +45,7 @@ class DataScopeController extends AbstractController summary: '查看用户数据权限', description: '返回用户的 scope 列表（含实体名称）和解析后的 store_ids', security: [['bearerAuth' => []]], - tags: ['DataScope'], + tags: ['Data Scope'], parameters: [ new OA\Parameter(name: 'id', in: 'path', required: true, description: '用户 ID', schema: new OA\Schema(type: 'integer')), ], @@ -126,7 +126,7 @@ class DataScopeController extends AbstractController summary: '设置用户数据权限', description: '全量替换用户的 scope 绑定，并重建 bitmap', security: [['bearerAuth' => []]], - tags: ['DataScope'], + tags: ['Data Scope'], parameters: [ new OA\Parameter(name: 'id', in: 'path', required: true, description: '用户 ID', schema: new OA\Schema(type: 'integer')), ], diff --git a/backend/app/Controller/api/v1/RouteGroupController.php b/backend/app/Controller/api/v1/RouteGroupController.php index bf18cae..449e010 100644 --- a/backend/app/Controller/api/v1/RouteGroupController.php +++ b/backend/app/Controller/api/v1/RouteGroupController.php @@ -15,7 +15,7 @@ use Hyperf\HttpServer\Annotation\RequestMapping; use OpenApi\Attributes as OA; use Psr\Http\Message\ResponseInterface; -#[OA\Tag(name: 'RouteGroups', description: '路由组管理')] +#[OA\Tag(name: 'Route Groups', description: '路由组管理')] #[Controller(prefix: "/api/v1/route-groups")] class RouteGroupController extends AbstractController { @@ -29,7 +29,7 @@ class RouteGroupController extends AbstractController summary: '路由组列表', description: '返回所有路由组，包含每组的路由数量', security: [['bearerAuth' => []]], - tags: ['RouteGroups'], + tags: ['Route Groups'], responses: [ new OA\Response( response: 200, @@ -76,7 +76,7 @@ class RouteGroupController extends AbstractController path: '/route-groups', summary: '创建路由组', security: [['bearerAuth' => []]], - tags: ['RouteGroups'], + tags: ['Route Groups'], requestBody: new OA\RequestBody( required: true, content: new OA\JsonContent( @@ -198,7 +198,7 @@ class RouteGroupController extends AbstractController path: '/route-groups/{id}', summary: '更新路由组', security: [['bearerAuth' => []]], - tags: ['RouteGroups'], + tags: ['Route Groups'], parameters: [ new OA\Parameter(name: 'id', in: 'path', required: true, description: '路由组 ID', schema: new OA\Schema(type: 'integer')), ], @@ -331,7 +331,7 @@ class RouteGroupController extends AbstractController summary: '删除路由组', description: '删除路由组，组内路由 group_id 自动设为 NULL，role_route_groups 关联自动级联删除', security: [['bearerAuth' => []]], - tags: ['RouteGroups'], + tags: ['Route Groups'], parameters: [ new OA\Parameter(name: 'id', in: 'path', required: true, description: '路由组 ID', schema: new OA\Schema(type: 'integer')), ], @@ -380,7 +380,7 @@ class RouteGroupController extends AbstractController summary: '路由列表', description: '获取全部路由列表，含分组信息，支持按 group_id、method、path 筛选', security: [['bearerAuth' => []]], - tags: ['RouteGroups'], + tags: ['Route Groups'], parameters: [ new OA\Parameter(name: 'group_id', in: 'query', required: false, description: '路由组 ID，传 0 或 "ungrouped" 筛选未分组路由', schema: new OA\Schema(type: 'string')), new OA\Parameter(name: 'method', in: 'query', required: false, description: 'HTTP 方法筛选', schema: new OA\Schema(type: 'string')), @@ -460,7 +460,7 @@ class RouteGroupController extends AbstractController summary: '分配路由到路由组', description: '将路由分配到指定路由组，传 group_id=null 表示从分组中移出', security: [['bearerAuth' => []]], - tags: ['RouteGroups'], + tags: ['Route Groups'], parameters: [ new OA\Parameter(name: 'id', in: 'path', required: true, description: '路由 ID', schema: new OA\Schema(type: 'integer')), ], diff --git a/backend/app/Storage/MemoryTableStorage.php b/backend/app/Storage/MemoryTableStorage.php index 7e9ba14..cd29e82 100644 --- a/backend/app/Storage/MemoryTableStorage.php +++ b/backend/app/Storage/MemoryTableStorage.php @@ -1,4 +1,8 @@ -