commit 75103e731ad8b77ad71846065b3230c251d6cebc Author: bid-docs <bid-docs@localhost> Date: 2026-01-21T11:19:08+08:00 Add docs REST API and iteration tracking diff --git a/docs/18-docs-rest-api.md b/docs/18-docs-rest-api.md new file mode 100644 index 0000000..4970568 --- /dev/null +++ b/docs/18-docs-rest-api.md @@ -0,0 +1,53 @@ +# 文档 REST API (Docs REST API) + +> 说明：API 用于标准化获取文档列表、内容、历史与迭代信息。 + +## 1. 认证 +- Header：`Authorization: Bearer <BID_API_TOKEN>` +- 备用 Header：`X-API-Key: <BID_API_TOKEN>` + +## 2. 基础路径 +- 线上：`https://bid.hao.work/docs/api/` +- 本地：`http://127.0.0.1:8090/api/` + +## 3. 接口清单 +### 3.1 获取文档列表 +`GET /api/docs` + +Response: +```json +{ "code": 0, "message": "ok", "data": [{"path":"01-product-requirements.md","updated_time":"2026-01-21 10:45"}] } +``` + +### 3.2 获取文档内容 +`GET /api/docs/content?path=01-product-requirements.md` + +可选渲染 HTML：`render=1` + +### 3.3 获取文档历史 +`GET /api/docs/history?path=01-product-requirements.md` + +### 3.4 获取文档差异 +`GET /api/docs/diff?path=01-product-requirements.md&hash=<commit>` + +### 3.5 迭代信息 +- `GET /api/iterations` +- `POST /api/iterations` + +POST Body 示例： +```json +{ + "version": "v0.1.1", + "title": "需求完善", + "summary": "补充数据源与API说明", + "docs": ["04-data-sources-catalog.md", "10-rest-api-spec.md"], + "author": "admin" +} +``` + +## 4. 错误码 +- `40101` 未认证或 Token 错误 +- `40001` 参数错误 +- `40401` 资源不存在 +- `50001` 服务错误 +