From 97d927edce61fb9372fc7221d59152fd66eb38df Mon Sep 17 00:00:00 2001
From: anghunk <anghunk@gmail.com>
Date: Wed, 21 Jan 2026 11:59:33 +0800
Subject: [PATCH] =?UTF-8?q?docs(api):=20=E5=AE=8C=E5=96=84API=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3=E6=A0=BC=E5=BC=8F=EF=BC=8C=E4=B8=BA=E6=AF=8F=E4=B8=AA?=
 =?UTF-8?q?=E6=8E=A5=E5=8F=A3=E6=B7=BB=E5=8A=A0=E4=B8=AD=E6=96=87=E6=A0=87?=
 =?UTF-8?q?=E9=A2=98=E5=92=8C=E4=BB=A3=E7=A0=81=E5=9D=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

为提升文档可读性，将API接口的标题改为中文描述并在下方添加代码块格式的HTTP方法及路径。
修改涉及公共API和管理员API两部分文档。
---
 docs/api/admin.md  | 60 ++++++++++++++++++++++++++++++++++++++--------
 docs/api/public.md | 18 +++++++++++---
 2 files changed, 65 insertions(+), 13 deletions(-)

diff --git a/docs/api/admin.md b/docs/api/admin.md
index 1948762..0e855fd 100644
--- a/docs/api/admin.md
+++ b/docs/api/admin.md
@@ -10,7 +10,11 @@ Authorization: Bearer <token>
 
 Token 通过登录接口获取，有效期为 24 小时。
 
-## POST /admin/login
+## 管理员登录
+
+```
+POST /admin/login
+```
 
 管理员登录，获取后续调用其他管理员接口所需的临时 Token。
 
@@ -89,7 +93,11 @@ Token 通过登录接口获取，有效期为 24 小时。
   }
   ```
 
-## GET /admin/comments/list
+## 获取评论列表
+
+```
+GET /admin/comments/list
+```
 
 获取评论列表，用于后台管理页面展示。
 
@@ -147,7 +155,11 @@ Token 通过登录接口获取，有效期为 24 小时。
   }
   ```
 
-## PUT /admin/comments/status
+## 更新评论状态
+
+```
+PUT /admin/comments/status
+```
 
 更新评论状态（例如通过 / 拒绝）。
 
@@ -197,7 +209,11 @@ Token 通过登录接口获取，有效期为 24 小时。
   }
   ```
 
-## DELETE /admin/comments/delete
+## 删除指定评论
+
+```
+DELETE /admin/comments/delete
+```
 
 删除指定评论。
 
@@ -241,7 +257,11 @@ Token 通过登录接口获取，有效期为 24 小时。
   }
   ```
 
-## GET /admin/comments/export
+## 导出所有评论数据
+
+```
+GET /admin/comments/export
+```
 
 导出所有评论数据，返回格式为 JSON，字段与数据库结构一致。
 
@@ -286,7 +306,11 @@ Token 通过登录接口获取，有效期为 24 小时。
   }
   ```
 
-## POST /admin/comments/import
+## 导入评论数据
+
+```
+POST /admin/comments/import
+```
 
 导入评论数据，支持 JSON 格式，可以是单个对象或数组。
 
@@ -350,7 +374,11 @@ Token 通过登录接口获取，有效期为 24 小时。
   }
   ```
 
-## GET /admin/settings/email
+## 获取当前通知邮箱配置
+
+```
+GET /admin/settings/email
+```
 
 获取当前通知邮箱配置。
 
@@ -378,7 +406,11 @@ Token 通过登录接口获取，有效期为 24 小时。
 }
 ```
 
-## PUT /admin/settings/email
+## 设置通知邮箱
+
+```
+PUT /admin/settings/email
+```
 
 设置通知邮箱，用于接收新评论提醒。
 
@@ -430,7 +462,11 @@ Token 通过登录接口获取，有效期为 24 小时。
   }
   ```
 
-## GET /admin/settings/comments
+## 获取评论配置
+
+```
+GET /admin/settings/comments
+```
 
 获取评论配置，例如博主邮箱、徽标、头像前缀、管理员密钥等。
 
@@ -478,7 +514,11 @@ Token 通过登录接口获取，有效期为 24 小时。
 }
 ```
 
-## PUT /admin/settings/comments
+## 更新评论配置
+
+```
+PUT /admin/settings/comments
+```
 
 更新评论配置。
 
diff --git a/docs/api/public.md b/docs/api/public.md
index 98eb2a7..e9cec90 100644
--- a/docs/api/public.md
+++ b/docs/api/public.md
@@ -4,7 +4,11 @@
 
 包含路径、方法、参数、请求体和响应示例。
 
-## GET /api/comments
+## 获取指定文章的评论列表
+
+```
+GET /api/comments
+```
 
 获取指定文章的评论列表。
 
@@ -91,7 +95,11 @@
   }
   ```
 
-## POST /api/comments
+## 提交新评论或回复
+
+```
+POST /api/comments
+```
 
 提交新评论或回复。
 
@@ -220,7 +228,11 @@
   }
   ```
 
-## GET /api/config/comments
+## 获取评论相关的公开配置
+
+```
+GET /api/config/comments
+```
 
 获取评论相关的公开配置，用于前端组件读取博主邮箱、徽标等信息。