erpnew/docs/api_docs_schema_usage_2026-07-03.md

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

登录接口：

POST /api/auth/login/

请求体：

{
  "username": "frontend-reviewer",
  "password": "your-password"
}

成功响应：

{
  "refresh": "refresh-token",
  "access": "access-token"
}

说明：

• 登录用户必须绑定 Employee。
• 未绑定员工身份的用户会登录失败。
• 当前 access token 有效期由后端 SIMPLE_JWT 配置控制。

访问 /api/schema/

请求：

GET /api/schema/
Authorization: Bearer {access-token}

curl 示例：

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：

Authorization: Bearer {access-token}

访问 /api/docs/

浏览器直接访问：

https://your-domain/api/docs/

如果浏览器没有携带 JWT，会返回 401。

推荐审查流程：

1. 调用 /api/auth/login/ 获取 access。
2. 打开 /api/docs/。
3. 点击 Swagger UI 页面右上角 Authorize。
4. 输入：

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