157 lines
3.9 KiB
Markdown
157 lines
3.9 KiB
Markdown
# ephron.ren API 文档
|
||
|
||
> 版本: v1.0
|
||
> 更新日期: 2026-05-05
|
||
> 状态: 已实现
|
||
|
||
---
|
||
|
||
## 概述
|
||
|
||
本文档记录 ephron.ren 已实现的所有 API 接口。
|
||
|
||
### 服务架构
|
||
|
||
| 服务 | 域名 | 说明 |
|
||
|------|------|------|
|
||
| Auth | auth.ephron.ren | 认证授权 |
|
||
| Blog | blog.ephron.ren | 博客系统 |
|
||
| Canvas | canvas.ephron.ren | 代码画布 |
|
||
| Prompt | prompt.ephron.ren | 提示词管理 |
|
||
|
||
### 权限级别
|
||
|
||
| 权限 | 标识 | 说明 |
|
||
|------|------|------|
|
||
| 🟢 公开 | `public` | 无需认证 |
|
||
| 🔵 用户 | `user` | 需要登录 |
|
||
| 🟡 服务 | `service` | 需要 Service Token |
|
||
|
||
### 认证方式
|
||
|
||
| 方式 | Header | 说明 |
|
||
|------|--------|------|
|
||
| Cookie | `ephron_auth` | 浏览器访问 |
|
||
| Bearer Token | `Authorization: Bearer {token}` | 服务间调用 |
|
||
|
||
---
|
||
|
||
## Auth 服务
|
||
|
||
### 用户认证
|
||
|
||
| 方法 | 路径 | 权限 | 说明 |
|
||
|------|------|------|------|
|
||
| POST | `/login` | 🟢 公开 | 用户登录 |
|
||
| POST | `/register` | 🟢 公开 | 用户注册 |
|
||
| POST | `/logout` | 🔵 用户 | 用户登出 |
|
||
| GET | `/check-username` | 🟢 公开 | 检查用户名可用 |
|
||
|
||
### 认证验证
|
||
|
||
| 方法 | 路径 | 权限 | 说明 |
|
||
|------|------|------|------|
|
||
| GET | `/auth/verify` | 🟢 公开 | 验证认证状态 |
|
||
| GET | `/authz/service-admin` | 🟡 服务 | 验证服务管理员 |
|
||
|
||
---
|
||
|
||
## Blog 服务
|
||
|
||
### 文章管理（服务API）
|
||
|
||
| 方法 | 路径 | 权限 | 说明 |
|
||
|------|------|------|------|
|
||
| GET | `/api/service/posts` | 🟡 服务 | 文章列表 |
|
||
| GET | `/api/service/posts/{slug}` | 🟡 服务 | 文章详情 |
|
||
| POST | `/api/service/posts` | 🟡 服务 | 创建文章 |
|
||
| PATCH | `/api/service/posts/{slug}` | 🟡 服务 | 更新文章 |
|
||
| DELETE | `/api/service/posts/{slug}` | 🟡 服务 | 删除文章 |
|
||
|
||
### 点赞功能
|
||
|
||
| 方法 | 路径 | 权限 | 说明 |
|
||
|------|------|------|------|
|
||
| GET | `/posts/{post_slug}/likes` | 🟢 公开 | 获取点赞状态 |
|
||
| POST | `/posts/{post_slug}/likes/toggle` | 🟢 公开 | 切换点赞 |
|
||
| GET | `/posts/{post_slug}/likes/stats` | 🟢 公开 | 点赞统计 |
|
||
|
||
### 评论功能
|
||
|
||
| 方法 | 路径 | 权限 | 说明 |
|
||
|------|------|------|------|
|
||
| GET | `/posts/{post_slug}/comments` | 🟢 公开 | 获取评论列表 |
|
||
| POST | `/posts/{post_slug}/comments` | 🔵 用户 | 添加评论 |
|
||
|
||
### 订阅与站点
|
||
|
||
| 方法 | 路径 | 权限 | 说明 |
|
||
|------|------|------|------|
|
||
| GET | `/feed` | 🟢 公开 | RSS 订阅 |
|
||
| GET | `/sitemap.xml` | 🟢 公开 | 站点地图 |
|
||
|
||
---
|
||
|
||
## Canvas 服务
|
||
|
||
### 画布管理（服务API）
|
||
|
||
| 方法 | 路径 | 权限 | 说明 |
|
||
|------|------|------|------|
|
||
| GET | `/api/service/canvas` | 🟡 服务 | 画布列表 |
|
||
| GET | `/api/service/canvas/{slug}` | 🟡 服务 | 画布详情 |
|
||
| POST | `/api/service/canvas` | 🟡 服务 | 创建画布 |
|
||
| PATCH | `/api/service/canvas/{slug}` | 🟡 服务 | 更新画布 |
|
||
| DELETE | `/api/service/canvas/{slug}` | 🟡 服务 | 删除画布 |
|
||
|
||
---
|
||
|
||
## Prompt 服务
|
||
|
||
### 公开API
|
||
|
||
| 方法 | 路径 | 权限 | 说明 |
|
||
|------|------|------|------|
|
||
| GET | `/api/prompts` | 🟢 公开 | 提示词列表 |
|
||
| GET | `/api/prompts/{key}` | 🟢 公开 | 提示词详情 |
|
||
|
||
### 服务API
|
||
|
||
| 方法 | 路径 | 权限 | 说明 |
|
||
|------|------|------|------|
|
||
| GET | `/api/service/prompts` | 🟡 服务 | 提示词列表 |
|
||
| GET | `/api/service/prompts/{key}` | 🟡 服务 | 提示词详情 |
|
||
| POST | `/api/service/prompts` | 🟡 服务 | 创建草稿 |
|
||
| PATCH | `/api/service/prompts/{key}` | 🟡 服务 | 更新草稿 |
|
||
| DELETE | `/api/service/prompts/{key}` | 🟡 服务 | 删除草稿 |
|
||
|
||
---
|
||
|
||
## 错误响应
|
||
|
||
```json
|
||
{
|
||
"detail": "错误信息"
|
||
}
|
||
```
|
||
|
||
| HTTP | 说明 |
|
||
|------|------|
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 未认证 |
|
||
| 403 | 无权限 |
|
||
| 404 | 资源不存在 |
|
||
| 500 | 服务器错误 |
|
||
|
||
---
|
||
|
||
## 统计
|
||
|
||
| 服务 | API数量 |
|
||
|------|---------|
|
||
| Auth | 6 |
|
||
| Blog | 12 |
|
||
| Canvas | 5 |
|
||
| Prompt | 7 |
|
||
| **总计** | **30** |
|