forked from erp-dev/erp
138 lines
3.1 KiB
Markdown
138 lines
3.1 KiB
Markdown
# API Docs 与 Schema 使用说明
|
||
|
||
更新日期：2026-07-03
|
||
|
||
本文档说明 `/api/schema/` 和 `/api/docs/` 的用途、登录方式和前端审查使用流程。
|
||
|
||
## 访问保护
|
||
|
||
当前 API 文档端点已启用 JWT 登录保护：
|
||
|
||
- 未登录访问 `/api/schema/` 会返回 401。
|
||
- 未登录访问 `/api/docs/` 会返回 401。
|
||
- 只要是有效登录用户即可访问，不额外要求管理员权限。
|
||
|
||
## 两个端点的区别
|
||
|
||
### `/api/schema/`
|
||
|
||
机器可读的 OpenAPI schema。
|
||
|
||
用途：
|
||
|
||
- 给 Apifox、Postman、Swagger Editor 导入。
|
||
- 给前端生成接口类型或客户端代码。
|
||
- 用于审查当前后端实际暴露的 API 路径、请求参数、响应结构和认证方式。
|
||
|
||
返回格式通常是 OpenAPI JSON。
|
||
|
||
### `/api/docs/`
|
||
|
||
浏览器可读的 Swagger UI 页面。
|
||
|
||
用途：
|
||
|
||
- 在浏览器里查看接口文档。
|
||
- 在页面中通过 Authorize 填入 JWT 后调试接口。
|
||
|
||
注意：Swagger UI 页面本身也需要登录保护。浏览器地址栏不能直接携带 `Authorization` header，因此最顺手的方式通常是先用工具拿到 token，再在 Swagger UI 的 Authorize 里填入 token。
|
||
|
||
## 登录获取 JWT
|
||
|
||
登录接口：
|
||
|
||
```http
|
||
POST /api/auth/login/
|
||
```
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"username": "frontend-reviewer",
|
||
"password": "your-password"
|
||
}
|
||
```
|
||
|
||
成功响应：
|
||
|
||
```json
|
||
{
|
||
"refresh": "refresh-token",
|
||
"access": "access-token"
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- 登录用户必须绑定 `Employee`。
|
||
- 未绑定员工身份的用户会登录失败。
|
||
- 当前 access token 有效期由后端 `SIMPLE_JWT` 配置控制。
|
||
|
||
## 访问 `/api/schema/`
|
||
|
||
请求：
|
||
|
||
```http
|
||
GET /api/schema/
|
||
Authorization: Bearer {access-token}
|
||
```
|
||
|
||
curl 示例：
|
||
|
||
```bash
|
||
curl -H "Authorization: Bearer ${ACCESS_TOKEN}" https://your-domain/api/schema/
|
||
```
|
||
|
||
Apifox/Postman 使用方式：
|
||
|
||
1. 先调用 `/api/auth/login/` 获取 `access`。
|
||
2. 导入 OpenAPI URL：`https://your-domain/api/schema/`。
|
||
3. 给导入请求添加 Header：
|
||
|
||
```http
|
||
Authorization: Bearer {access-token}
|
||
```
|
||
|
||
## 访问 `/api/docs/`
|
||
|
||
浏览器直接访问：
|
||
|
||
```text
|
||
https://your-domain/api/docs/
|
||
```
|
||
|
||
如果浏览器没有携带 JWT，会返回 401。
|
||
|
||
推荐审查流程：
|
||
|
||
1. 调用 `/api/auth/login/` 获取 `access`。
|
||
2. 打开 `/api/docs/`。
|
||
3. 点击 Swagger UI 页面右上角 `Authorize`。
|
||
4. 输入：
|
||
|
||
```text
|
||
Bearer {access-token}
|
||
```
|
||
|
||
5. 之后即可在 Swagger UI 中查看并调试接口。
|
||
|
||
## 前端审查建议
|
||
|
||
- 如果目标是审查接口结构，优先使用 `/api/schema/` 导入 Apifox/Postman。
|
||
- 如果目标是临时浏览和手动调试，使用 `/api/docs/`。
|
||
- 不要把 `/api/schema/` 的内容提交到前端仓库作为长期静态副本；schema 会随着后端代码变化而变化。
|
||
- 审查前请确认使用的是目标环境的域名，因为 `content_type` 等 ID 在不同环境可能不同。
|
||
|
||
## 当前抽检重点
|
||
|
||
本次配置变更后需要确认：
|
||
|
||
- 匿名访问 `/api/schema/` 返回 401。
|
||
- 匿名访问 `/api/docs/` 返回 401。
|
||
- 登录后访问 `/api/schema/` 返回 200。
|
||
- 登录后访问 `/api/docs/` 返回 200。
|
||
- `/api/schema/` 中包含最新 mission API 变更，例如 `employee_type_ids`。
|
||
|
||
更新日期：2026-07-03
|