102 lines
4.4 KiB
Markdown
102 lines
4.4 KiB
Markdown
# 8.7 API 接口总览
|
||
|
||
:::tip 概述
|
||
全部接口经 gmeta 注解自动生成 OpenAPI：GET /api.json（原生 JSON）+ GET /swagger（本地 Redoc UI）。本节给出接口域总览与权限码总规律，完整清单以 /api.json 为准。
|
||
:::
|
||
|
||
## 在线文档
|
||
|
||
```text
|
||
GET /swagger 本地托管 Redoc 页面（免登录；内置页依赖境外 CDN，已改本地托管）
|
||
GET /api.json 原生 OpenAPI JSON（gmeta 补注册闭包路由后全量可用）
|
||
```
|
||
|
||
gmeta 的 method/path/summary/permission 会完整体现在文档中——接口与文档天然同步。
|
||
|
||
## 接口域总览（27 模块 170+ 接口）
|
||
|
||
| 域 | 模块 | 路由前缀 | 说明 |
|
||
|----|------|---------|------|
|
||
| auth | （无表） | /api/login 等顶层 | 登录/登出/验证码/令牌（公开+顶层） |
|
||
| index | （无表） | /api/index/* | 个人中心（登录即可） |
|
||
| system | user | /api/user | 用户（含导入导出/重置密码） |
|
||
| | role | /api/role | 角色（权限分配/data_scope） |
|
||
| | menu | /api/menu | 菜单（树形） |
|
||
| | dept | /api/dept | 部门（树形） |
|
||
| | level | /api/level | 职级（导入导出） |
|
||
| | position | /api/position | 岗位 |
|
||
| | tenant | /api/tenant | 租户（开户/用户列表） |
|
||
| data | config | /api/config | 配置（+web/index、web/save） |
|
||
| | config_item | /api/config/item | 配置项 |
|
||
| | param | /api/param | 参数 |
|
||
| | dict | /api/dict | 字典（+refreshCache、dictionary 别名） |
|
||
| | dict_item | /api/dict/item | 字典项（+getDictItemList） |
|
||
| | notice | /api/notice | 公告 |
|
||
| | city | /api/city（别名 /api/area） | 行政区划（级联懒加载） |
|
||
| content | article | /api/article | 文章（富文本/多图） |
|
||
| | category | /api/category | 分类（树形） |
|
||
| | link | /api/link | 友链 |
|
||
| monitor | operation_log | /api/oper/log | 操作日志（仅查询删除） |
|
||
| | login_log | /api/login/log | 登录日志（仅查询删除） |
|
||
| | job | /api/job | 定时任务（+runOnce/pause/resume/daemonStatus） |
|
||
| | job_log | /api/job/log | 任务日志（仅查询删除） |
|
||
| | online_user | /api/onlineUser | 在线用户（无表，Redis） |
|
||
| | server_monitor | /api/server | 服务器监控（无表） |
|
||
| | cache_monitor | /api/cache | 缓存监控（无表） |
|
||
| tool | example | /api/example | 案例演示（导入导出） |
|
||
| | file_template | /api/file/template | 文件模板（+getTemplateByCode） |
|
||
| | generator | /api/generator | 代码生成（page/preview/generate/batchGenerate） |
|
||
| | upload | /api/upload | 上传（uploadFile/uploadFiles） |
|
||
|
||
基础设施（router.go 手工注册）：`GET /api/health`（公开）、`GET /swagger`、`GET /api.json`、`GET /upload/**`（静态）。
|
||
|
||
## 标准接口形态（七件套 + 扩展）
|
||
|
||
```text
|
||
GET /api/{prefix}/page 分页
|
||
GET /api/{prefix}/list 列表（下拉/树形）
|
||
GET /api/{prefix}/detail/:id 详情
|
||
POST /api/{prefix}/add 新增
|
||
PUT /api/{prefix}/update 修改
|
||
DELETE /api/{prefix}/delete/:id 删除（软删）
|
||
DELETE /api/{prefix}/batchDelete 批量删除（body {ids:[]}）
|
||
扩展：PUT /api/{prefix}/status（状态）
|
||
POST /api/{prefix}/import · GET /api/{prefix}/export（导入导出）
|
||
```
|
||
|
||
## 权限码总规律
|
||
|
||
```text
|
||
sys:{模块小驼峰}:{动作}
|
||
动作与方法名一致：page/list/detail/add/update/delete/batchDelete/
|
||
status/import/export/resetPwd/execute/pause/resume/
|
||
savePermission/getPermission/cache/users/save 等
|
||
|
||
特例：配置网站 sys:configWeb:data|save
|
||
生成器 sys:generator:generator|batchGenerator
|
||
上传 sys:upload:file|files
|
||
|
||
超管（ROLE_SUPER_ADMIN）绕过全部权限校验
|
||
```
|
||
|
||
## 公开路由（免登录白名单）
|
||
|
||
```text
|
||
/api/login · /api/register（白名单放行，路由未注册）· /api/captcha
|
||
/api/oauth2/token · /api/health
|
||
另放行 /api.json 与 /swagger*（文档）
|
||
|
||
三处一致：middleware/public.go 白名单 / gmeta public:"true" / router.go 手工注册
|
||
全部路由不带 /v1 版本段
|
||
```
|
||
|
||
## 通用约定速记
|
||
|
||
```text
|
||
认证：Authorization: Bearer <access_token>（登录接口返回 access_token 下划线）
|
||
响应：{code, ok, msg, data}；0 成功 / 1 失败 / 401 未认证
|
||
分页：PageData[T]（records/total/size/current/pages）
|
||
命名：出入参驼峰（例外仅登录/令牌接口四字段）
|
||
限流：普通 120/分钟/IP/路径；认证入口 10/分钟/IP
|
||
```
|