8.7 API 接口总览

概述

全部接口经 gmeta 注解自动生成 OpenAPI：GET /api.json（原生 JSON）+ GET /swagger（本地 Redoc UI）。本节给出接口域总览与权限码总规律，完整清单以 /api.json 为准。

在线文档

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/**（静态）。

标准接口形态（七件套 + 扩展）

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（导入导出）

权限码总规律

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）绕过全部权限校验

公开路由（免登录白名单）

/api/login · /api/register（白名单放行，路由未注册）· /api/captcha
/api/oauth2/token · /api/health
另放行 /api.json 与 /swagger*（文档）

三处一致：middleware/public.go 白名单 / gmeta public:"true" / router.go 手工注册
全部路由不带 /v1 版本段

通用约定速记

认证：Authorization: Bearer <access_token>（登录接口返回 access_token 下划线）
响应：{code, ok, msg, data}；0 成功 / 1 失败 / 401 未认证
分页：PageData[T]（records/total/size/current/pages）
命名：出入参驼峰（例外仅登录/令牌接口四字段）
限流：普通 120/分钟/IP/路径；认证入口 10/分钟/IP