docs: 添加 API 文档和 OpenClaw Skill
- 新增 docs/API_DOC.md API 接口文档 - 新增 .claude/skills/zjpb-api.md OpenClaw 集成说明 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Jowe
325
docs/API_DOC.md
Normal file
325
docs/API_DOC.md
Normal file
@@ -0,0 +1,325 @@
|
||||
# ZJPB API 文档
|
||||
|
||||
## 概述
|
||||
|
||||
ZJPB 网站管理 API，通过 API Key 进行认证，可用于外部工具（如 OpenClaw）调用。
|
||||
|
||||
## 基础信息
|
||||
|
||||
- **Base URL**: `http://175.178.72.171`
|
||||
- **认证方式**: Header (`X-API-Key`)
|
||||
- **数据格式**: JSON
|
||||
|
||||
## 认证
|
||||
|
||||
所有 API 请求需要在 Header 中携带 API Key：
|
||||
|
||||
```
|
||||
X-API-Key: your-api-key-here
|
||||
```
|
||||
|
||||
获取 API Key：进入后台管理 → API密钥 → 创建新密钥
|
||||
|
||||
---
|
||||
|
||||
## API 接口
|
||||
|
||||
### 1. 获取网站列表
|
||||
|
||||
```http
|
||||
GET /api/key/sites
|
||||
```
|
||||
|
||||
**权限**: `site:read`
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"sites": [
|
||||
{
|
||||
"id": 1,
|
||||
"code": "12345678",
|
||||
"name": "网站名称",
|
||||
"url": "https://example.com",
|
||||
"slug": "example",
|
||||
"logo": "/uploads/logo.png",
|
||||
"short_desc": "简短描述",
|
||||
"description": "详细介绍",
|
||||
"features": "主要功能",
|
||||
"news_keywords": "关键词",
|
||||
"is_active": true,
|
||||
"is_recommended": false,
|
||||
"view_count": 100,
|
||||
"tags": ["标签1", "标签2"],
|
||||
"created_at": "2026-03-23 10:00:00"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. 创建网站
|
||||
|
||||
```http
|
||||
POST /api/key/sites
|
||||
```
|
||||
|
||||
**权限**: `site:write`
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"name": "网站名称",
|
||||
"url": "https://example.com",
|
||||
"slug": "example",
|
||||
"logo": "/uploads/logo.png",
|
||||
"short_desc": "简短描述",
|
||||
"description": "详细介绍",
|
||||
"features": "主要功能",
|
||||
"news_keywords": "关键词",
|
||||
"tags": ["标签1", "标签2"],
|
||||
"is_active": true,
|
||||
"is_recommended": false,
|
||||
"sort_order": 0
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明**:
|
||||
| 字段 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| name | 是 | 网站名称 |
|
||||
| url | 是 | 网站 URL |
|
||||
| slug | 否 | URL别名，用于 SEO |
|
||||
| logo | 否 | Logo 图片路径 |
|
||||
| short_desc | 否 | 简短描述 |
|
||||
| description | 否 | 详细介绍 |
|
||||
| features | 否 | 主要功能 |
|
||||
| news_keywords | 否 | 新闻关键词 |
|
||||
| tags | 否 | 标签数组 |
|
||||
| is_active | 否 | 是否启用，默认 true |
|
||||
| is_recommended | 否 | 是否推荐，默认 false |
|
||||
| sort_order | 否 | 排序权重，默认 0 |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"site": {
|
||||
"id": 2,
|
||||
"code": "87654321",
|
||||
"name": "网站名称",
|
||||
"url": "https://example.com",
|
||||
"slug": "example"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. 获取单个网站
|
||||
|
||||
```http
|
||||
GET /api/key/sites/{code}
|
||||
```
|
||||
|
||||
**权限**: `site:read`
|
||||
|
||||
**参数**:
|
||||
- `code`: 网站编码（8位数字）
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"site": {
|
||||
"id": 1,
|
||||
"code": "12345678",
|
||||
"name": "网站名称",
|
||||
"url": "https://example.com",
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. 更新网站
|
||||
|
||||
```http
|
||||
PUT /api/key/sites/{code}
|
||||
```
|
||||
|
||||
**权限**: `site:write`
|
||||
|
||||
**参数**:
|
||||
- `code`: 网站编码（8位数字）
|
||||
|
||||
**请求体**: 同创建网站，可只传需要更新的字段
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"site": {
|
||||
"id": 1,
|
||||
"code": "12345678",
|
||||
"name": "新名称",
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. 删除网站
|
||||
|
||||
```http
|
||||
DELETE /api/key/sites/{code}
|
||||
```
|
||||
|
||||
**权限**: `site:write`
|
||||
|
||||
**参数**:
|
||||
- `code`: 网站编码（8位数字）
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "网站已删除"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 错误响应
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "错误信息"
|
||||
}
|
||||
```
|
||||
|
||||
**状态码**:
|
||||
- `200`: 成功
|
||||
- `400`: 请求参数错误
|
||||
- `401`: 认证失败（无效的 API Key）
|
||||
- `403`: 权限不足
|
||||
- `404`: 资源不存在
|
||||
- `500`: 服务器错误
|
||||
|
||||
---
|
||||
|
||||
## 使用示例
|
||||
|
||||
### cURL
|
||||
|
||||
```bash
|
||||
# 获取网站列表
|
||||
curl -X GET http://175.178.72.171/api/key/sites \
|
||||
-H "X-API-Key: your-api-key"
|
||||
|
||||
# 创建网站
|
||||
curl -X POST http://175.178.72.171/api/key/sites \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: your-api-key" \
|
||||
-d '{
|
||||
"name": "示例网站",
|
||||
"url": "https://example.com",
|
||||
"short_desc": "这是一个示例网站",
|
||||
"tags": ["科技", "开源"]
|
||||
}'
|
||||
|
||||
# 更新网站
|
||||
curl -X PUT http://175.178.72.171/api/key/sites/12345678 \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: your-api-key" \
|
||||
-d '{"name": "新名称"}'
|
||||
|
||||
# 删除网站
|
||||
curl -X DELETE http://175.178.72.171/api/key/sites/12345678 \
|
||||
-H "X-API-Key: your-api-key"
|
||||
```
|
||||
|
||||
### Python
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
API_KEY = "your-api-key"
|
||||
BASE_URL = "http://175.178.72.171"
|
||||
headers = {"X-API-Key": API_KEY}
|
||||
|
||||
# 获取网站列表
|
||||
response = requests.get(f"{BASE_URL}/api/key/sites", headers=headers)
|
||||
print(response.json())
|
||||
|
||||
# 创建网站
|
||||
data = {
|
||||
"name": "示例网站",
|
||||
"url": "https://example.com",
|
||||
"short_desc": "这是一个示例网站",
|
||||
"tags": ["科技", "开源"]
|
||||
}
|
||||
response = requests.post(f"{BASE_URL}/api/key/sites", json=data, headers=headers)
|
||||
print(response.json())
|
||||
```
|
||||
|
||||
### JavaScript
|
||||
|
||||
```javascript
|
||||
const API_KEY = "your-api-key";
|
||||
const BASE_URL = "http://175.178.72.171";
|
||||
const headers = { "X-API-Key": API_KEY };
|
||||
|
||||
// 获取网站列表
|
||||
fetch(`${BASE_URL}/api/key/sites`, { headers })
|
||||
.then(res => res.json())
|
||||
.then(data => console.log(data));
|
||||
|
||||
// 创建网站
|
||||
fetch(`${BASE_URL}/api/key/sites`, {
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
"X-API-Key": API_KEY
|
||||
},
|
||||
body: JSON.stringify({
|
||||
name: "示例网站",
|
||||
url: "https://example.com",
|
||||
short_desc: "这是一个示例网站"
|
||||
})
|
||||
})
|
||||
.then(res => res.json())
|
||||
.then(data => console.log(data));
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## OpenClaw 集成
|
||||
|
||||
在 OpenClaw 中配置 API：
|
||||
|
||||
1. **Base URL**: `http://175.178.72.171`
|
||||
2. **Auth Header**: `X-API-Key`
|
||||
3. **Auth Value**: 你创建的 API Key
|
||||
|
||||
创建网站的 prompt 示例：
|
||||
|
||||
```
|
||||
你是一个网站发布助手。请根据用户提供的网站信息，调用 ZJPB API 创建网站。
|
||||
|
||||
网站信息：
|
||||
- 名称：{name}
|
||||
- URL：{url}
|
||||
- 描述：{description}
|
||||
|
||||
请调用 POST /api/key/sites 接口创建网站。
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**最后更新**: 2026-03-23
|
||||
Reference in New Issue
Block a user