# 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
```