4.7 KiB
4.7 KiB
API 管理 admin 接口
基本信息
- 模块：sys_api
- 资源：API 管理
- 端：admin
- 鉴权：默认
PrivateGroup，需要JWT + Casbin；/api/freshCasbin挂PublicGroup - 审计：除
getAllApis/getApiList/getApiRoles/freshCasbin外，其余接口启用OperationRecord - 前缀：
/api - 模型：
system.SysApi、system.SysIgnoreApi；搜索：systemReq.SearchApiParams；角色绑定：systemReq.SetApiAuthorities - 返回：统一
response.Response
接口
| 动作 | Method | 路径 | 入参 | 返回重点 |
|---|---|---|---|---|
| 创建 API | POST |
/api/createApi |
system.SysApi body |
操作结果 |
| 删除 API | POST |
/api/deleteApi |
system.SysApi body，仅需 ID |
操作结果 |
| 批量删除 API | DELETE |
/api/deleteApisByIds |
request.IdsReq body |
操作结果 |
| 更新 API | POST |
/api/updateApi |
system.SysApi body |
操作结果 |
| API 详情 | POST |
/api/getApiById |
request.GetById body |
api |
| API 分页列表 | POST |
/api/getApiList |
systemReq.SearchApiParams body |
response.PageResult |
| 全量 API 列表 | POST |
/api/getAllApis |
无 | apis |
| API 分组 | GET |
/api/getApiGroups |
无 | groups/apiGroupMap |
| 预览同步差异 | GET |
/api/syncApi |
无 | newApis/deleteApis/ignoreApis |
| 忽略/取消忽略 API | POST |
/api/ignoreApi |
system.SysIgnoreApi body |
操作结果 |
| 确认同步路由 | POST |
/api/enterSyncApi |
空 body 或 systemRes.SysSyncApis |
操作结果 |
| 获取 API 关联角色 | GET |
/api/getApiRoles |
path/method query |
uint[] |
| 覆盖 API 关联角色 | POST |
/api/setApiRoles |
systemReq.SetApiAuthorities body |
操作结果 |
| 刷新 Casbin 缓存 | GET |
/api/freshCasbin |
无 | 操作结果 |
请求字段
SysApi Body
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| ID | uint | 更新/删除必填 | API ID；来自 global.GVA_MODEL 的 JSON 字段 |
| path | string | 创建/更新必填 | API 路径 |
| description | string | 创建/更新必填 | API 中文描述 |
| apiGroup | string | 创建/更新必填 | API 分组 |
| method | string | 创建/更新必填 | HTTP Method |
SearchApiParams Body
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| page/pageSize | int | 是 | 页码/每页数量 |
| path | string | 否 | API 路径筛选 |
| description | string | 否 | API 描述筛选 |
| apiGroup | string | 否 | API 分组筛选 |
| method | string | 否 | HTTP Method 筛选 |
| orderKey | string | 否 | 排序字段 |
| desc | bool | 否 | 是否倒序 |
SysIgnoreApi Body
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| path | string | 是 | API 路径 |
| method | string | 是 | HTTP Method |
| flag | bool | 是 | true 写入忽略；false 取消忽略 |
其他 Body/Query
| 场景 | 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| getApiById | id | int | 是 | API ID；此处使用 request.GetById，字段为小写 id |
| deleteApisByIds | ids | int[] | 是 | API ID 数组 |
| enterSyncApi | newApis | system.SysApi[] | 否 | 兼容旧请求体；传入时按列表新增 |
| enterSyncApi | deleteApis | system.SysApi[] | 否 | 兼容旧请求体；传入时按列表删除 |
| getApiRoles | path | string | 是 | API 路径 |
| getApiRoles | method | string | 是 | HTTP Method |
| setApiRoles | path | string | 是 | API 路径 |
| setApiRoles | method | string | 是 | HTTP Method |
| setApiRoles | authorityIds | uint[] | 是 | 全量覆盖后的角色 ID 列表 |
响应字段
| 场景 | 字段 | 类型 | 说明 |
|---|---|---|---|
| getApiById | api | object | system.SysApi |
| getApiList | list/total/page/pageSize | mixed | 分页结果 |
| getAllApis | apis | array | system.SysApi 列表 |
| getApiGroups | groups | string[] | API 分组列表 |
| getApiGroups | apiGroupMap | object | 路径首段到 API 分组映射 |
| syncApi | newApis/deleteApis/ignoreApis | array | 待新增、待删除、已忽略 API |
| getApiRoles | data | uint[] | 角色 ID 列表 |
规则
path + method唯一；创建重复 API 返回失败。/api/syncApi只预览差异，不写库。/api/enterSyncApi空 body 时以global.GVA_ROUTERS为事实来源同步sys_apis。- 同步时新路由按
path + method新增；已有路由保留人工维护的description/apiGroup。 sys_ignore_apis中的path + method不写入sys_apis。- 当前路由表不存在的旧 API 从
sys_apis删除，并清理对应 Casbin 权限。 setApiRoles为全量覆盖，成功后刷新 Casbin 缓存。- 默认管理员角色
888必须具备/api/getApiRoles与/api/setApiRoles权限。