# 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