8.8 API 接口总览

概述

全部接口由 RouteSpec 声明派生，可经 OpenAPI 端点（/api.json）与 Swagger UI（/swagger）在线查看——文档与运行时元数据同源，永不漂移。

在线文档端点

端点	内容
GET /api.json	OpenAPI JSON（接口清单、schema、权限码、公开标记）
/swagger	Swagger UI（浏览与调试）

开关：api.docs（生产建议关闭，防暴露接口清单与权限码元数据）。端点免登录（基础设施白名单）。

文档内容来源

RouteSpec 声明（Method/Path/Summary/Permission/Public）
   + 方法签名反射（ReqType/ResType → 请求/响应 schema，binding/msg/dc 标签）
   → OpenAPI 生成

改声明即改文档，无需维护第二份接口清单。

接口分域速览

域	前缀	模块
认证	/api/login、/api/captcha、/api/oauth2/*	登录/验证码/令牌
个人中心	/api/index/*	用户信息/菜单/改密
组织权限	/api/user、/api/role、/api/menu、/api/dept、/api/level、/api/position、/api/tenant	系统管理
内容	/api/article、/api/category、/api/notice、/api/link	内容管理
数据配置	/api/dict、/api/dict/item、/api/dictionary/*、/api/param、/api/config、/api/city	数据管理
任务监控	/api/job、/api/jobLog、/api/onlineUser、/api/serverMonitor、/api/cacheMonitor	监控中心
日志	/api/operationLog、/api/loginLog	审计
文件	/api/upload/、/api/file/template/	文件与模板
工具	/api/example/、/api/generator/	示例与生成器

完整清单以在线文档为准（运行时生成，覆盖实际注册的全部路由）。

约定回顾

• 请求/响应字段：小驼峰（dto json 标签）
• 分页：pageNo/pageSize → PageData 五字段（8.3）
• 信封：0/1/401 三值语义（8.1）
• 认证：Bearer access token（8.7）

第三方对接建议

1. 从 /api.json 拉取清单生成客户端桩
2. 公开接口仅 /api/login、/api/captcha、/api/oauth2/token（其余需令牌）
3. 分页拉取用 Page 接口；字典取值用 /api/dict/item/getDictItemList/{code}

下一步

→ 第 9 章 前端开发