API 文档 - YuThree

Base URL /api

🔐

认证 Auth

POST /api/auth/login 用户登录公开 ▶

请求体 (JSON)

参数名	类型	必填	说明
username	string	必填	用户名
password	string	必填	密码

请求示例

{
  "username": "admin",
  "password": "your_password"
}

成功响应 200

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "username": "admin"
}

失败响应 401

{
  "message": "用户名或密码错误"
}

GET /api/auth/registration-status 检查注册功能是否开放公开 ▶

{
  "enabled": true
}

POST /api/auth/send-code 发送邮箱验证码公开 ▶

参数名	类型	必填	说明
email	string	必填	接收验证码的邮箱地址

{
  "email": "user@example.com"
}

成功响应 200

{
  "message": "验证码已发送",
  "expiresIn": 300
}

POST /api/auth/verify-register 验证邮箱并注册公开 ▶

参数名	类型	必填	说明
email	string	必填	邮箱地址
code	string	必填	邮箱收到的验证码
username	string	必填	用户名
password	string	必填	密码（至少 6 位）

{
  "email": "user@example.com",
  "code": "123456",
  "username": "new_user",
  "password": "123456"
}

成功响应 201

{
  "message": "注册成功，请登录"
}

GET /api/auth/me 获取当前用户信息需认证 ▶

请求头

参数名	类型	必填	说明
Authorization	string	必填	Bearer <token>，登录后获取

成功响应 200

{
  "_id": "665a1b2c...",
  "username": "admin",
  "email": "admin@example.com",
  "emailVerified": true,
  "createdAt": "2024-06-01T00:00:00.000Z"
}

POST /api/auth/register 管理员注册（首个用户无需认证，后续需认证）条件 ▶

参数名	类型	必填	说明
username	string	必填	用户名
password	string	必填	密码

{
  "message": "注册成功"
}

📝

文章 Articles

GET /api/articles 获取文章列表（分页、筛选）公开 ▶

参数名	类型	必填	说明
page	number	可选	页码，默认 1
limit	number	可选	每页数量，默认 10
category	string	可选	按分类筛选
tag	string	可选	按标签筛选
published	boolean	可选	是否已发布（true/false）

{
  "articles": [{
    "_id": "665a1b2c...",
    "title": "Hello World",
    "slug": "hello-world",
    "content": "# Hello World\n...",
    "excerpt": "文章摘要",
    "categories": ["技术"],
    "tags": ["Hexo", "Blog"],
    "thumbnail": "",
    "published": true,
    "toc": true,
    "createdAt": "2024-06-01T00:00:00.000Z",
    "updatedAt": "2024-06-01T00:00:00.000Z"
  }],
  "totalPages": 5,
  "currentPage": 1,
  "total": 42
}

GET /api/articles/id/:id 按 ID 获取文章公开 ▶

参数名	位置	类型	必填	说明
id	path	string	必填	文章 MongoDB ID

{
  "_id": "665a1b2c...",
  "title": "Hello World",
  "slug": "hello-world",
  "content": "# Hello World\n## 这是第一篇文章",
  "categories": ["技术"],
  "tags": ["Hexo"],
  "published": true,
  "createdAt": "2024-06-01T00:00:00.000Z",
  "updatedAt": "2024-06-01T00:00:00.000Z"
}

GET /api/articles/:slug 按 slug 获取文章公开 ▶

参数名	位置	类型	说明
slug	path	string	文章 URL 友好标识

// GET /api/articles/hello-world
{
  "_id": "665a1b2c...",
  "title": "Hello World",
  "slug": "hello-world",
  "content": "# Hello World\n...",
  "published": true
}

POST /api/articles 创建文章需认证 ▶

参数名	类型	必填	说明
title	string	必填	文章标题
content	string	必填	Markdown 正文内容
categories	string[]	可选	分类列表
tags	string[]	可选	标签列表
published	boolean	可选	是否直接发布，默认 false
thumbnail	string	可选	封面图 URL
toc	boolean	可选	是否显示目录，默认 true

请求示例

{
  "title": "我的新文章",
  "content": "## 正文内容\n这是文章正文。\n\n",
  "categories": ["技术", "前端"],
  "tags": ["React", "TypeScript"],
  "published": false
}

成功响应 201

{
  "_id": "665a1b2c...",
  "title": "我的新文章",
  "slug": "wo-de-xin-wen-zhang",
  "content": "## 正文内容\n...",
  "categories": ["技术", "前端"],
  "tags": ["React", "TypeScript"],
  "published": false,
  "createdAt": "2024-06-01T00:00:00.000Z",
  "updatedAt": "2024-06-01T00:00:00.000Z"
}

PUT /api/articles/:id 更新文章需认证 ▶

参数名	类型	必填	说明
title	string	可选	新标题（更新后 slug 自动重新生成）
content	string	可选	Markdown 正文
categories	string[]	可选	分类列表
tags	string[]	可选	标签列表
published	boolean	可选	发布状态

// 返回更新后的完整文章对象
{
  "_id": "665a1b2c...",
  "title": "更新后的标题",
  "slug": "geng-xin-hou-de-biao-ti",
  "content": "更新后的内容...",
  "published": true,
  "updatedAt": "2024-06-02T00:00:00.000Z"
}

DELETE /api/articles/:id 删除文章需认证 ▶

{
  "message": "文章已删除"
}

POST /api/articles/:id/publish 发布文章（触发 Hexo 生成）需认证 ▶

{
  "message": "文章已发布",
  "article": { ... }
}

PUT /api/articles/:id/date 修改发布时间（仅 admin）需认证+Admin ▶

参数名	类型	必填	说明
createdAt	string	必填	ISO 8601 日期字符串

{
  "message": "文章时间已更新",
  "article": { ... }
}

⚙️

配置 Config

GET /api/config 获取所有配置公开 ▶

[
  {
    "_id": "...",
    "key": "beian",
    "value": "蜀ICP备xxxx号",
    "updatedAt": "2024-06-01T00:00:00.000Z"
  },
  {
    "_id": "...",
    "key": "registration_enabled",
    "value": "true"
  }
]

GET /api/config/:key 按 key 获取单个配置公开 ▶

参数名	位置	类型	说明
key	path	string	配置键名，例如 beian、registration_enabled

// GET /api/config/beian
{
  "_id": "...",
  "key": "beian",
  "value": "蜀ICP备xxxx号",
  "updatedAt": "2024-06-01T00:00:00.000Z"
}

PUT /api/config/:key 更新配置需认证 ▶

参数名	类型	必填	说明
value	string	必填	新的配置值

{
  "_id": "...",
  "key": "beian",
  "value": "蜀ICP备xxxx号-1",
  "updatedAt": "2024-06-02T00:00:00.000Z"
}

POST /api/config/batch 批量更新配置需认证 ▶

参数名	类型	必填	说明
configs	object[]	必填	配置数组 [{key, value}]

// 请求
{
  "configs": [
    { "key": "beian", "value": "蜀ICP备xxxx号-1" },
    { "key": "site_title", "value": "My Blog" }
  ]
}

// 响应
[
  { "_id": "...", "key": "beian", "value": "蜀ICP备xxxx号-1", ... },
  { "_id": "...", "key": "site_title", "value": "My Blog", ... }
]

👥

用户 Users

GET /api/users 用户列表（不含密码）需认证 ▶

[
  {
    "_id": "665a1b2c...",
    "username": "admin",
    "email": "admin@example.com",
    "emailVerified": true,
    "createdAt": "2024-06-01T00:00:00.000Z"
  }
]

POST /api/users 创建用户需认证 ▶

参数名	类型	必填	说明
username	string	必填	用户名（唯一）
password	string	必填	密码（至少 6 位）

{
  "_id": "665a1b2c...",
  "username": "new_user",
  "createdAt": "2024-06-01T00:00:00.000Z"
}

DELETE /api/users/:id 删除用户（不能删除自己）需认证 ▶

{
  "message": "用户已删除"
}

PUT /api/users/:id/reset-password 重置用户密码需认证 ▶

参数名	类型	必填	说明
password	string	必填	新密码（至少 6 位）

{
  "message": "密码已重置"
}

✅

TODO 事项

GET /api/todos 获取 TODO 列表（支持筛选）公开 ▶

参数名	类型	必填	说明
completed	boolean	可选	筛选完成状态（true/false）
priority	string	可选	按优先级筛选：low / medium / high
tag	string	可选	按标签筛选

[
  {
    "_id": "665a1b2c...",
    "title": "完成 API 文档",
    "content": "编写完整的接口文档",
    "completed": false,
    "priority": "high",
    "dueDate": "2024-06-30T00:00:00.000Z",
    "tags": ["文档", "API"],
    "notes": "需要包含所有接口",
    "createdAt": "2024-06-01T00:00:00.000Z",
    "updatedAt": "2024-06-01T00:00:00.000Z"
  }
]

POST /api/todos 创建 TODO 公开 ▶

参数名	类型	必填	说明
title	string	必填	标题（最多 200 字符）
content	string	可选	内容（最多 2000 字符）
priority	string	可选	优先级：low / medium（默认）/ high
dueDate	string	可选	截止日期 ISO 字符串
tags	string[]	可选	标签列表（每个最多 50 字符）
notes	string	可选	备注（最多 1000 字符）

// 请求
{
  "title": "写周报",
  "priority": "high",
  "tags": ["工作", "周报"],
  "dueDate": "2024-06-07T00:00:00.000Z"
}

// 响应 201
{
  "_id": "665a1b2c...",
  "title": "写周报",
  "priority": "high",
  "tags": ["工作", "周报"],
  "completed": false,
  "createdAt": "2024-06-01T00:00:00.000Z"
}

PUT /api/todos/:id 更新 TODO 公开 ▶

// 返回更新后的完整 TODO 对象
{
  "_id": "665a1b2c...",
  "title": "写周报（已更新）",
  "completed": true,
  "updatedAt": "2024-06-02T00:00:00.000Z"
}

DELETE /api/todos/:id 删除 TODO 公开 ▶

{
  "message": "删除成功"
}

PATCH /api/todos/:id/toggle 切换完成状态公开 ▶

{
  "_id": "665a1b2c...",
  "title": "写周报",
  "completed": true,
  ...
}

🌐

翻译 Translate

POST /api/translate 翻译文本（多引擎）公开 ▶

参数名	类型	必填	说明
query	string	必填	待翻译文本
from	string	可选	源语言，默认 auto
to	string	可选	目标语言，默认 en

// 请求
{
  "query": "你好世界",
  "from": "zh",
  "to": "en"
}

// 响应（同时返回百度+腾讯+Azure翻译结果）
{
  "results": [
    {
      "source": "baidu",
      "result": "Hello world"
    },
    {
      "source": "tencent",
      "result": "Hello World"
    },
    {
      "source": "azure",
      "result": "Hello, world"
    }
  ]
}

POST /api/translate/folder-name 中文名转英文文件夹名公开 ▶

参数名	类型	必填	说明
name	string	必填	中文名称

// 请求
{ "name": "我的第一个项目" }

// 响应
{
  "results": [
    { "source": "baidu", "result": "my-first-project" },
    { "source": "tencent", "result": "my-first-project" }
  ]
}

🖼️

Unsplash 图片

GET /api/unsplash/photo-url 获取 Unsplash 图片直链公开 ▶

参数名	位置	类型	必填	说明
url	query	string	必填	Unsplash 图片页面 URL

// GET /api/unsplash/photo-url?url=https://unsplash.com/photos/abc123

{
  "photoUrl": "https://images.unsplash.com/photo-xxx?w=1920",
  "author": "Photographer Name",
  "authorUrl": "https://unsplash.com/@author"
}

YuThree Blog API 文档

认证 Auth

请求体 (JSON)

请求示例

成功响应 200

失败响应 401

成功响应 200

成功响应 201

请求头

成功响应 200

文章 Articles

请求示例

成功响应 201

配置 Config

用户 Users

TODO 事项

翻译 Translate

Unsplash 图片