chore: 移除旧的 API 技能文档
This commit is contained in:
1 parent
fa38d81ab5
commit
3890777e10
1 file changed
-103
@@ -1,103 +0,0 @@
|
|||||||
---
|
|
||||||
name: blogflare-api
|
|
||||||
description: 如何调用 BlogFlare 本地或线上的 REST API 来管理(增删改查)文章,附带 OpenAPI schema 与使用示例。
|
|
||||||
---
|
|
||||||
|
|
||||||
# BlogFlare API 操作指南
|
|
||||||
|
|
||||||
当用户要求你“通过接口/API读取文章”、“通过接口更新文章”或者当你需要远程管理 BlogFlare 的数据时,请使用本指南提供的 RESTful API。
|
|
||||||
|
|
||||||
## 认证机制
|
|
||||||
|
|
||||||
所有 `/api/v1/posts` 下的接口都需要在 HTTP 请求头中带上 `Authorization: Bearer <Token>`。
|
|
||||||
其中 Token 需要保存在数据库 `settings` 表的 `agent.api_token` 字段中。
|
|
||||||
|
|
||||||
**如果在本地开发环境 (dev) 调试:**
|
|
||||||
如果遇到 Token 未设置,你可以先帮用户在 `settings` 表插入/更新:
|
|
||||||
`INSERT INTO settings (key, value) VALUES ('agent.api_token', 'your_test_token') ON CONFLICT(key) DO UPDATE SET value = excluded.value;`
|
|
||||||
|
|
||||||
## 接口说明
|
|
||||||
|
|
||||||
### 1. 获取文章列表 (GET `/api/v1/posts`)
|
|
||||||
|
|
||||||
**参数:**
|
|
||||||
|
|
||||||
- `limit` (默认 10)
|
|
||||||
- `offset` (默认 0)
|
|
||||||
|
|
||||||
**响应格式:**
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"data": [
|
|
||||||
{
|
|
||||||
"id": 1,
|
|
||||||
"slug": "hello-world",
|
|
||||||
"title": "...",
|
|
||||||
"published_at": "...",
|
|
||||||
"category_slug": "..."
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"meta": { "total": 10, "limit": 10, "offset": 0 }
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. 获取单篇文章详情 (GET `/api/v1/posts/[slug]`)
|
|
||||||
|
|
||||||
**响应格式:**
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"data": {
|
|
||||||
"id": 1,
|
|
||||||
"slug": "hello-world",
|
|
||||||
"title": "...",
|
|
||||||
"content": "...",
|
|
||||||
"published_at": "...",
|
|
||||||
"updated_at": "...",
|
|
||||||
"category_slug": "tech"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. 创建新文章 (POST `/api/v1/posts`)
|
|
||||||
|
|
||||||
**Body (JSON):**
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"slug": "new-post-slug",
|
|
||||||
"title": "New Post Title",
|
|
||||||
"content": "Markdown content here...",
|
|
||||||
"category_slug": "tech"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**响应格式:**
|
|
||||||
|
|
||||||
```json
|
|
||||||
{ "success": true, "slug": "new-post-slug", "title": "New Post Title" }
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4. 更新文章 (PUT `/api/v1/posts/[slug]`)
|
|
||||||
|
|
||||||
**Body (JSON) [可选字段]:**
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"title": "Updated Title",
|
|
||||||
"content": "Updated Markdown content...",
|
|
||||||
"category_slug": "life"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**响应格式:**
|
|
||||||
|
|
||||||
```json
|
|
||||||
{ "success": true, "slug": "the-post-slug" }
|
|
||||||
```
|
|
||||||
|
|
||||||
## 注意事项
|
|
||||||
|
|
||||||
- 本地调试可以运行 `npm run dev`,然后用 `curl` 测试。
|
|
||||||
- 请勿随意删除或覆盖已有的真实文章数据。在更新之前,最好先 GET 取回全量 content 进行 diff 确认。
|
|
||||||
Reference in new issue
Block a user