feat: #386 #380

Author: vastsa

docs/api/index.md

@@ -15,6 +15,29 @@
 Authorization: Bearer <token>
 ```
 
+### 获取 Token
+
+当管理面板关闭了游客上传（`openUpload=0`）时，需要先登录获取 token：
+
+```bash
+curl -X POST "http://localhost:12345/admin/login" \
+  -H "Content-Type: application/json" \
+  -d '{"password": "FileCodeBox2023"}'
+```
+
+**响应示例：**
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "detail": {
+    "token": "xxx.xxx.xxx",
+    "token_type": "Bearer"
+  }
+}
+```
+
 ## 分享接口
 
 ### 分享文本
@@ -29,7 +52,22 @@ Authorization: Bearer <token>
 |-------|------|------|--------|------|
 | text | string | 是 | - | 要分享的文本内容 |
 | expire_value | integer | 否 | 1 | 过期时间值 |
-| expire_style | string | 否 | "day" | 过期时间单位(day/hour/minute) |
+| expire_style | string | 否 | "day" | 过期时间单位(day/hour/minute/count/forever) |
+
+**cURL 示例：**
+
+```bash
+# 游客上传（openUpload=1 时）
+curl -X POST "http://localhost:12345/share/text/" \
+  -F "text=这是要分享的文本内容" \
+  -F "expire_value=1" \
+  -F "expire_style=day"
+
+# 需要认证时（openUpload=0 时）
+curl -X POST "http://localhost:12345/share/text/" \
+  -H "Authorization: Bearer xxx.xxx.xxx" \
+  -F "text=这是要分享的文本内容"
+```
 
 **响应示例：**
 
@@ -38,8 +76,7 @@ Authorization: Bearer <token>
   "code": 200,
   "msg": "success",
   "detail": {
-    "code": "abc123",
-    "name": "text.txt"
+    "code": "abc123"
   }
 }
 ```
@@ -56,7 +93,32 @@ Authorization: Bearer <token>
 |-------|------|------|--------|------|
 | file | file | 是 | - | 要上传的文件 |
 | expire_value | integer | 否 | 1 | 过期时间值 |
-| expire_style | string | 否 | "day" | 过期时间单位(day/hour/minute) |
+| expire_style | string | 否 | "day" | 过期时间单位(day/hour/minute/count/forever) |
+
+**cURL 示例：**
+
+```bash
+# 上传文件（默认1天有效期）
+curl -X POST "http://localhost:12345/share/file/" \
+  -F "file=@/path/to/file.txt"
+
+# 上传文件（7天有效期）
+curl -X POST "http://localhost:12345/share/file/" \
+  -F "file=@/path/to/file.txt" \
+  -F "expire_value=7" \
+  -F "expire_style=day"
+
+# 上传文件（可下载10次）
+curl -X POST "http://localhost:12345/share/file/" \
+  -F "file=@/path/to/file.txt" \
+  -F "expire_value=10" \
+  -F "expire_style=count"
+
+# 需要认证时
+curl -X POST "http://localhost:12345/share/file/" \
+  -H "Authorization: Bearer xxx.xxx.xxx" \
+  -F "file=@/path/to/file.txt"
+```
 
 **响应示例：**
 
@@ -75,14 +137,21 @@ Authorization: Bearer <token>
 
 **GET** `/share/select/`
 
-通过分享码获取文件信息。
+通过分享码获取文件信息（直接下载文件）。
 
 **请求参数：**
 
 | 参数名 | 类型 | 必填 | 描述 |
 |-------|------|------|------|
 | code | string | 是 | 文件分享码 |
 
+**cURL 示例：**
+
+```bash
+# 通过取件码下载文件
+curl -L "http://localhost:12345/share/select/?code=abc123" -o downloaded_file
+```
+
 **响应示例：**
 
 ```json

docs/en/api/index.md

@@ -15,6 +15,29 @@ Some APIs require `Authorization` header for authentication:
 Authorization: Bearer <token>
 ```
 
+### Get Token
+
+When guest upload is disabled in admin panel (`openUpload=0`), you need to login first:
+
+```bash
+curl -X POST "http://localhost:12345/admin/login" \
+  -H "Content-Type: application/json" \
+  -d '{"password": "FileCodeBox2023"}'
+```
+
+**Response Example:**
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "detail": {
+    "token": "xxx.xxx.xxx",
+    "token_type": "Bearer"
+  }
+}
+```
+
 ## Share API
 
 ### Share Text
@@ -29,7 +52,22 @@ Share text content and get a share code.
 |-----------|------|----------|---------|-------------|
 | text | string | Yes | - | Text content to share |
 | expire_value | integer | No | 1 | Expiration time value |
-| expire_style | string | No | "day" | Expiration time unit(day/hour/minute) |
+| expire_style | string | No | "day" | Expiration time unit(day/hour/minute/count/forever) |
+
+**cURL Example:**
+
+```bash
+# Guest upload (when openUpload=1)
+curl -X POST "http://localhost:12345/share/text/" \
+  -F "text=This is the text content to share" \
+  -F "expire_value=1" \
+  -F "expire_style=day"
+
+# When authentication required (openUpload=0)
+curl -X POST "http://localhost:12345/share/text/" \
+  -H "Authorization: Bearer xxx.xxx.xxx" \
+  -F "text=This is the text content to share"
+```
 
 **Response Example:**
 
@@ -38,8 +76,7 @@ Share text content and get a share code.
   "code": 200,
   "msg": "success",
   "detail": {
-    "code": "abc123",
-    "name": "text.txt"
+    "code": "abc123"
   }
 }
 ```
@@ -56,7 +93,32 @@ Upload and share a file, get a share code.
 |-----------|------|----------|---------|-------------|
 | file | file | Yes | - | File to upload |
 | expire_value | integer | No | 1 | Expiration time value |
-| expire_style | string | No | "day" | Expiration time unit(day/hour/minute) |
+| expire_style | string | No | "day" | Expiration time unit(day/hour/minute/count/forever) |
+
+**cURL Example:**
+
+```bash
+# Upload file (default 1 day expiration)
+curl -X POST "http://localhost:12345/share/file/" \
+  -F "file=@/path/to/file.txt"
+
+# Upload file (7 days expiration)
+curl -X POST "http://localhost:12345/share/file/" \
+  -F "file=@/path/to/file.txt" \
+  -F "expire_value=7" \
+  -F "expire_style=day"
+
+# Upload file (10 downloads limit)
+curl -X POST "http://localhost:12345/share/file/" \
+  -F "file=@/path/to/file.txt" \
+  -F "expire_value=10" \
+  -F "expire_style=count"
+
+# When authentication required
+curl -X POST "http://localhost:12345/share/file/" \
+  -H "Authorization: Bearer xxx.xxx.xxx" \
+  -F "file=@/path/to/file.txt"
+```
 
 **Response Example:**
 
@@ -75,14 +137,21 @@ Upload and share a file, get a share code.
 
 **GET** `/share/select/`
 
-Get file information by share code.
+Get file information by share code (direct file download).
 
 **Parameters:**
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | code | string | Yes | File share code |
 
+**cURL Example:**
+
+```bash
+# Download file by extraction code
+curl -L "http://localhost:12345/share/select/?code=abc123" -o downloaded_file
+```
+
 **Response Example:**
 
 ```json

docs/en/guide/upload.md

@@ -118,11 +118,52 @@ Content-Type: `multipart/form-data`
 **cURL example:**
 
 ```bash
+# Upload file (default 1 day expiration)
+curl -X POST "http://localhost:12345/share/file/" \
+  -F "file=@/path/to/file.pdf"
+
+# Upload file with 7 days expiration
 curl -X POST "http://localhost:12345/share/file/" \
   -F "file=@/path/to/file.pdf" \
   -F "expire_value=7" \
   -F "expire_style=day"
+
+# Upload file with 10 downloads limit
+curl -X POST "http://localhost:12345/share/file/" \
+  -F "file=@/path/to/file.pdf" \
+  -F "expire_value=10" \
+  -F "expire_style=count"
+
+# Share text
+curl -X POST "http://localhost:12345/share/text/" \
+  -F "text=This is the text content to share"
+
+# Download file by extraction code
+curl -L "http://localhost:12345/share/select/?code=YOUR_CODE" -o downloaded_file
+```
+
+::: tip When Authentication Required
+If guest upload is disabled in admin panel (`openUpload=0`), you need to login first:
+
+```bash
+# 1. Login to get token
+curl -X POST "http://localhost:12345/admin/login" \
+  -H "Content-Type: application/json" \
+  -d '{"password": "FileCodeBox2023"}'
+
+# Returns: {"code":200,"msg":"success","detail":{"token":"xxx.xxx.xxx","token_type":"Bearer"}}
+
+# 2. Upload file with token
+curl -X POST "http://localhost:12345/share/file/" \
+  -H "Authorization: Bearer xxx.xxx.xxx" \
+  -F "file=@/path/to/file.pdf"
+
+# 3. Share text with token
+curl -X POST "http://localhost:12345/share/text/" \
+  -H "Authorization: Bearer xxx.xxx.xxx" \
+  -F "text=This is the text content to share"
 ```
+:::
 
 
 ## Chunked Upload API

docs/guide/upload.md

@@ -118,11 +118,52 @@ Content-Type: `multipart/form-data`
 **cURL 示例：**
 
 ```bash
+# 上传文件（默认1天有效期）
+curl -X POST "http://localhost:12345/share/file/" \
+  -F "file=@/path/to/file.pdf"
+
+# 上传文件并指定有效期（7天）
 curl -X POST "http://localhost:12345/share/file/" \
   -F "file=@/path/to/file.pdf" \
   -F "expire_value=7" \
   -F "expire_style=day"
+
+# 上传文件并指定有效期（可下载10次）
+curl -X POST "http://localhost:12345/share/file/" \
+  -F "file=@/path/to/file.pdf" \
+  -F "expire_value=10" \
+  -F "expire_style=count"
+
+# 分享文本
+curl -X POST "http://localhost:12345/share/text/" \
+  -F "text=这是要分享的文本内容"
+
+# 通过取件码下载文件
+curl -L "http://localhost:12345/share/select/?code=取件码" -o downloaded_file
+```
+
+::: tip 需要认证时
+如果管理面板关闭了游客上传（`openUpload=0`），需要先登录获取 token：
+
+```bash
+# 1. 登录获取 token
+curl -X POST "http://localhost:12345/admin/login" \
+  -H "Content-Type: application/json" \
+  -d '{"password": "FileCodeBox2023"}'
+
+# 返回: {"code":200,"msg":"success","detail":{"token":"xxx.xxx.xxx","token_type":"Bearer"}}
+
+# 2. 使用 token 上传文件
+curl -X POST "http://localhost:12345/share/file/" \
+  -H "Authorization: Bearer xxx.xxx.xxx" \
+  -F "file=@/path/to/file.pdf"
+
+# 3. 使用 token 分享文本
+curl -X POST "http://localhost:12345/share/text/" \
+  -H "Authorization: Bearer xxx.xxx.xxx" \
+  -F "text=这是要分享的文本内容"
 ```
+:::
 
 ## 分片上传 API