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