58 lines
2.3 KiB
Markdown
58 lines
2.3 KiB
Markdown
# 8.8 API 接口总览
|
||
|
||
:::tip 概述
|
||
全部接口由 RouteSpec 声明派生，可经 **OpenAPI 端点**（/api.json）与 **Swagger UI**（/swagger）在线查看——文档与运行时元数据同源，永不漂移。
|
||
:::
|
||
|
||
## 在线文档端点
|
||
|
||
| 端点 | 内容 |
|
||
|---|---|
|
||
| GET /api.json | OpenAPI JSON（接口清单、schema、权限码、公开标记） |
|
||
| /swagger | Swagger UI（浏览与调试） |
|
||
|
||
开关：`api.docs`（生产建议关闭，防暴露接口清单与权限码元数据）。端点免登录（基础设施白名单）。
|
||
|
||
## 文档内容来源
|
||
|
||
```text
|
||
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](/zh/api-spec/pagination.html)）
|
||
- 信封：0/1/401 三值语义（[8.1](/zh/api-spec/response.html)）
|
||
- 认证：Bearer access token（[8.7](/zh/api-spec/token.html)）
|
||
|
||
## 第三方对接建议
|
||
|
||
1. 从 /api.json 拉取清单生成客户端桩
|
||
2. 公开接口仅 /api/login、/api/captcha、/api/oauth2/token（其余需令牌）
|
||
3. 分页拉取用 Page 接口；字典取值用 /api/dict/item/getDictItemList/{code}
|
||
|
||
## 下一步
|
||
|
||
→ [第 9 章 前端开发](/zh/frontend/overview.html)
|