docs(api): 添加 API 文档

2026-10-17 04:41:01 +08:00 · 2025-03-11 11:44:42 +08:00
parent 589dec3420
commit ee6e5463dd
1 changed files with 161 additions and 0 deletions
@@ -0,0 +1,161 @@
+以下是基于提供的 `api.json` 生成的 API 文档：
+
+---
+
+# VVQuest API 文档 (版本 0.1.0)
+
+---
+
+## 目录
+1. [接口概览](#接口概览)
+2. [接口详情](#接口详情)
+   - [搜索图片](#搜索图片)
+   - [生成缓存](#生成缓存)
+   - [获取配置](#获取配置)
+   - [更新配置](#更新配置)
+   - [下载模型](#下载模型)
+   - [模型列表](#模型列表)
+   - [切换模式](#切换模式)
+   - [切换模型](#切换模型)
+
+---
+
+## 接口概览
+| 接口路径           | 方法 | 描述                     |
+|--------------------|------|--------------------------|
+| `/search`          | POST | 执行图片搜索             |
+| `/generate-cache`  | POST | 触发缓存生成（后台任务） |
+| `/config`          | GET  | 获取当前配置             |
+| `/api-config`      | PUT  | 更新API配置              |
+| `/download-model`  | POST | 下载指定模型             |
+| `/models`          | GET  | 获取可用模型列表         |
+| `/mode/{mode}`     | PUT  | 切换运行模式             |
+| `/model/{model_id}`| PUT  | 切换本地模型             |
+
+---
+
+## 接口详情
+
+### 1. 搜索图片
+- **路径**: `/search`
+- **方法**: POST
+- **描述**: 执行图片搜索
+- **请求体** (application/json):
+  ```json
+  {
+    "query": "搜索关键词",
+    "n_results": 5  // 可选，默认值 5
+  }
+  ```
+- **成功响应**:
+  - 状态码: 200
+  - 内容: JSON 格式数据（具体字段需参考实现）
+
+- **错误响应**:
+  - 状态码: 422 (请求体验证失败)
+  - 内容: [HTTPValidationError](#HTTPValidationError)
+
+---
+
+### 2. 生成缓存
+- **路径**: `/generate-cache`
+- **方法**: POST
+- **描述**: 触发后台缓存生成任务
+- **成功响应**:
+  - 状态码: 200
+  - 内容: JSON 格式空对象
+
+---
+
+### 3. 获取配置
+- **路径**: `/config`
+- **方法**: GET
+- **描述**: 获取当前API配置
+- **成功响应**:
+  - 状态码: 200
+  - 内容: JSON 格式配置信息
+
+---
+
+### 4. 更新配置
+- **路径**: `/api-config`
+- **方法**: PUT
+- **描述**: 更新API配置
+- **请求体** (application/json):
+  ```json
+  {
+    "api_key": "新的API密钥",  // 可选（可为 null）
+    "base_url": "新的基础URL"  // 可选（可为 null）
+  }
+  ```
+- **成功响应**:
+  - 状态码: 200
+  - 内容: JSON 格式空对象
+
+- **错误响应**:
+  - 状态码: 422 (请求体验证失败)
+  - 内容: [HTTPValidationError](#HTTPValidationError)
+
+---
+
+### 5. 下载模型
+- **路径**: `/download-model`
+- **方法**: POST
+- **描述**: 下载指定模型
+- **请求体** (application/json):
+  ```json
+  {
+    "model_id": "模型ID"
+  }
+  ```
+- **成功响应**:
+  - 状态码: 200
+  - 内容: JSON 格式空对象
+
+- **错误响应**:
+  - 状态码: 422 (请求体验证失败)
+  - 内容: [HTTPValidationError](#HTTPValidationError)
+
+---
+
+### 6. 模型列表
+- **路径**: `/models`
+- **方法**: GET
+- **描述**: 获取可用模型列表
+- **成功响应**:
+  - 状态码: 200
+  - 内容: JSON 格式模型列表
+
+---
+
+### 7. 切换模式
+- **路径**: `/mode/{mode}`
+- **方法**: PUT
+- **描述**: 切换系统运行模式
+- **路径参数**:
+  - `mode` (字符串): 目标模式名称
+- **成功响应**:
+  - 状态码: 200
+  - 内容: JSON 格式空对象
+
+- **错误响应**:
+  - 状态码: 422 (参数验证失败)
+  - 内容: [HTTPValidationError](#HTTPValidationError)
+
+---
+
+### 8. 切换模型
+- **路径**: `/model/{model_id}`
+- **方法**: PUT
+- **描述**: 切换本地使用的模型
+- **路径参数**:
+  - `model_id` (字符串): 目标模型ID
+- **成功响应**:
+  - 状态码: 200
+  - 内容: JSON 格式空对象
+
+- **错误响应**:
+  - 状态码: 422 (参数验证失败)
+  - 内容: [HTTPValidationError](#HTTPValidationError)
+
+---