101 lines
4.7 KiB
Markdown
101 lines
4.7 KiB
Markdown
# 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` 权限。
|