2.3 KiB
2.3 KiB
8.8 API 接口总览
:::tip 概述 全部接口由 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）
第三方对接建议
- 从 /api.json 拉取清单生成客户端桩
- 公开接口仅 /api/login、/api/captcha、/api/oauth2/token（其余需令牌）
- 分页拉取用 Page 接口；字典取值用 /api/dict/item/getDictItemList/{code}