{"code":0,"data":{"tokenScope":"global","authHeader":"Authorization: Bearer <AI_UPLOAD_TOKEN>","endpoints":[{"method":"POST","path":"/api/ai/projects/upsert","desc":"创建/更新项目"},{"method":"POST","path":"/api/ai/categories/upsert","desc":"确保分类路径存在"},{"method":"POST","path":"/api/ai/documents/upsert","desc":"创建/更新单篇文档（幂等）"},{"method":"POST","path":"/api/ai/import/batch","desc":"批量创建/更新文档"},{"method":"POST","path":"/api/ai/import/openapi","desc":"导入 OpenAPI/Swagger"}],"markdown":"# LiteDoc AI 上传接口说明\n\n本站支持 AI / IDE 插件 / 脚本通过 HTTP 接口自动创建与更新 API 文档。\n\n## 认证\n所有 `/api/ai/*` 接口都需在**请求头**携带令牌（禁止放在 URL 查询参数里）：\n\n```\nAuthorization: Bearer <AI_UPLOAD_TOKEN>\n```\n\n**该令牌全站通用**：同一个令牌适用于所有项目、所有 AI 接口。令牌由站点环境变量 `AI_UPLOAD_TOKEN` 配置，或由管理员在「管理后台 → AI 令牌」在线生成/更换（生成后请立即保存，仅显示一次）。\n\n## 接口列表\n- `POST /api/ai/projects/upsert` 创建/更新项目\n- `POST /api/ai/categories/upsert` 确保分类路径存在\n- `POST /api/ai/documents/upsert` 创建/更新单篇文档（幂等）\n- `POST /api/ai/import/batch` 批量创建/更新文档（单条失败不影响其他）\n- `POST /api/ai/import/openapi` 导入 OpenAPI 3.x / Swagger 2.0（可 preview）\n\n## upsert 去重规则（幂等）\n- 提供 `externalId` 时：**只按 externalId** 判定同一文档（推荐，稳定幂等）。\n- 未提供 `externalId` 时：按 `projectSlug + method + path` 判定；再退化到 slug。\n- 已存在则更新、不存在则创建；更新前自动创建历史版本；重复调用不会产生重复文档。\n\n## 字段说明（document）\n- `title`(必填)、`slug`、`type`(\"api\"|\"markdown\")、`method`、`path`（**可为完整 URL**，如 https://api.example.com/x）、`summary`、`markdown`(正文)\n- 参数数组：`headers` / `pathParams` / `queryParams` / `bodyParams` / `responseParams`，元素为 `{ name, type, required, default, example, description }`\n- 示例：`requestExample` / `responseExample`(=成功示例) / `errorExample`（可为对象，将自动转 JSON 文本）\n\n## 文档 upsert 示例\n```bash\ncurl -X POST \"<站点地址>/api/ai/documents/upsert\" \\\n  -H \"Authorization: Bearer <AI_UPLOAD_TOKEN>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"projectSlug\": \"user-center\",\n    \"categoryPath\": [\"用户\", \"认证\"],\n    \"externalId\": \"user-login\",\n    \"document\": {\n      \"title\": \"用户登录\",\n      \"type\": \"api\",\n      \"method\": \"POST\",\n      \"path\": \"https://api.example.com/api/auth/login\",\n      \"summary\": \"使用账号和密码登录\",\n      \"bodyParams\": [\n        { \"name\": \"username\", \"type\": \"string\", \"required\": true, \"example\": \"admin\", \"description\": \"用户名\" }\n      ],\n      \"requestExample\": { \"username\": \"admin\", \"password\": \"123456\" },\n      \"responseExample\": { \"code\": 0, \"data\": { \"token\": \"example-token\" } }\n    }\n  }'\n```\n\n## 返回格式\n成功返回：\n```json\n{ \"success\": true, \"action\": \"created\", \"projectSlug\": \"user-center\", \"documentSlug\": \"user-login\", \"url\": \"/?project=user-center&doc=user-login\" }\n```\n令牌错误返回 401，数据错误返回 400；不会返回数据库堆栈信息。\n\n## 批量上传\n`POST /api/ai/import/batch`，body：`{ \"defaultProjectSlug\": \"user-center\", \"items\": [ { \"externalId\":\"...\", \"document\": {...} }, ... ] }`，单次最多 200 条，逐条返回成功/失败。\n"}}