fin

docs/api_docs_schema_usage_2026-07-03.md

@@ -0,0 +1,137 @@
+# 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