feat: add docs pages

2025-12-06 13:07:30 +08:00
parent f4780c9c6c
commit 42c7c9a1b4
22 changed files with 4547 additions and 0 deletions
@@ -0,0 +1,305 @@
+# 调用示例
+
+本页面提供各种编程语言的API调用示例。
+
+## CURL
+
+```bash
+curl -X POST --location 'http://127.0.0.1:8000/api/v1/message/send' \
+  --header 'Content-Type: application/json' \
+  --data '{
+    "token": "a3541c2f0d3e1b4a5c6d7e8f9a0b1c2d3e",
+    "title": "message title",
+    "text": "Hello World!"
+  }'
+```
+
+## Python
+
+```python
+import requests
+
+headers = {
+    'Content-Type': 'application/json',
+}
+
+json_data = {
+    "token": "a3541c2f0d3e1b4a5c6d7e8f9a0b1c2d3e",
+    "title": "message title",
+    "text": "Hello World!"
+}
+
+response = requests.post(
+    'http://127.0.0.1:8000/api/v1/message/send',
+    headers=headers,
+    json=json_data
+)
+
+print("response:", response.json())
+```
+
+### 使用 requests 库
+
+首先安装依赖：
+
+```bash
+pip install requests
+```
+
+## Go
+
+```go
+package main
+
+import (
+	"fmt"
+	"io"
+	"log"
+	"net/http"
+	"strings"
+)
+
+func main() {
+	client := &http.Client{}
+	var data = strings.NewReader(`{
+    "token": "a3541c2f0d3e1b4a5c6d7e8f9a0b1c2d3e",
+    "title": "message title",
+    "text": "Hello World!"
+}`)
+	req, err := http.NewRequest("POST", "http://127.0.0.1:8000/api/v1/message/send", data)
+	if err != nil {
+		log.Fatal(err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := client.Do(req)
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer resp.Body.Close()
+	bodyText, err := io.ReadAll(resp.Body)
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("%s\n", bodyText)
+}
+```
+
+## Java
+
+```java
+import java.io.IOException;
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpRequest.BodyPublishers;
+import java.net.http.HttpResponse;
+
+public class MessageNestExample {
+    public static void main(String[] args) throws IOException, InterruptedException {
+        HttpClient client = HttpClient.newBuilder()
+            .followRedirects(HttpClient.Redirect.NORMAL)
+            .build();
+
+        String jsonData = """
+            {
+                "token": "a3541c2f0d3e1b4a5c6d7e8f9a0b1c2d3e",
+                "title": "message title",
+                "text": "Hello World!"
+            }
+            """;
+
+        HttpRequest request = HttpRequest.newBuilder()
+            .uri(URI.create("http://127.0.0.1:8000/api/v1/message/send"))
+            .POST(BodyPublishers.ofString(jsonData))
+            .setHeader("Content-Type", "application/json")
+            .build();
+
+        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
+        
+        System.out.println(response.body());
+    }
+}
+```
+
+## Node.js
+
+### 使用 request 库
+
+```javascript
+var request = require('request');
+
+var headers = {
+    'Content-Type': 'application/json'
+};
+
+var dataString = JSON.stringify({
+    "token": "a3541c2f0d3e1b4a5c6d7e8f9a0b1c2d3e",
+    "title": "message title",
+    "text": "Hello World!"
+});
+
+var options = {
+    url: 'http://127.0.0.1:8000/api/v1/message/send',
+    method: 'POST',
+    headers: headers,
+    body: dataString
+};
+
+function callback(error, response, body) {
+    if (!error && response.statusCode == 200) {
+        console.log(body);
+    }
+}
+
+request(options, callback);
+```
+
+### 使用 axios 库
+
+```javascript
+const axios = require('axios');
+
+const data = {
+    token: "a3541c2f0d3e1b4a5c6d7e8f9a0b1c2d3e",
+    title: "message title",
+    text: "Hello World!"
+};
+
+axios.post('http://127.0.0.1:8000/api/v1/message/send', data, {
+    headers: {
+        'Content-Type': 'application/json'
+    }
+})
+.then(response => {
+    console.log('response:', response.data);
+})
+.catch(error => {
+    console.error('error:', error);
+});
+```
+
+### 使用 fetch (Node.js 18+)
+
+```javascript
+const data = {
+    token: "a3541c2f0d3e1b4a5c6d7e8f9a0b1c2d3e",
+    title: "message title",
+    text: "Hello World!"
+};
+
+fetch('http://127.0.0.1:8000/api/v1/message/send', {
+    method: 'POST',
+    headers: {
+        'Content-Type': 'application/json'
+    },
+    body: JSON.stringify(data)
+})
+.then(response => response.json())
+.then(data => {
+    console.log('response:', data);
+})
+.catch(error => {
+    console.error('error:', error);
+});
+```
+
+## PHP
+
+```php
+<?php
+$ch = curl_init();
+
+$data = array(
+    "token" => "a3541c2f0d3e1b4a5c6d7e8f9a0b1c2d3e",
+    "title" => "message title",
+    "text" => "Hello World!"
+);
+
+curl_setopt($ch, CURLOPT_URL, 'http://127.0.0.1:8000/api/v1/message/send');
+curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
+curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
+curl_setopt($ch, CURLOPT_HTTPHEADER, [
+    'Content-Type: application/json',
+]);
+curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
+curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
+
+$response = curl_exec($ch);
+
+if (curl_errno($ch)) {
+    echo 'Error:' . curl_error($ch);
+} else {
+    echo $response;
+}
+
+curl_close($ch);
+?>
+```
+
+## C#
+
+```csharp
+using System;
+using System.Net.Http;
+using System.Text;
+using System.Text.Json;
+using System.Threading.Tasks;
+
+class Program
+{
+    static async Task Main(string[] args)
+    {
+        using var client = new HttpClient();
+        
+        var data = new
+        {
+            token = "a3541c2f0d3e1b4a5c6d7e8f9a0b1c2d3e",
+            title = "message title",
+            text = "Hello World!"
+        };
+        
+        var json = JsonSerializer.Serialize(data);
+        var content = new StringContent(json, Encoding.UTF8, "application/json");
+        
+        var response = await client.PostAsync(
+            "http://127.0.0.1:8000/api/v1/message/send",
+            content
+        );
+        
+        var responseString = await response.Content.ReadAsStringAsync();
+        Console.WriteLine(responseString);
+    }
+}
+```
+
+## Ruby
+
+```ruby
+require 'net/http'
+require 'json'
+require 'uri'
+
+uri = URI('http://127.0.0.1:8000/api/v1/message/send')
+http = Net::HTTP.new(uri.host, uri.port)
+
+request = Net::HTTP::Post.new(uri.path, {
+  'Content-Type' => 'application/json'
+})
+
+request.body = {
+  token: 'a3541c2f0d3e1b4a5c6d7e8f9a0b1c2d3e',
+  title: 'message title',
+  text: 'Hello World!'
+}.to_json
+
+response = http.request(request)
+puts response.body
+```
+
+## 注意事项
+
+::: tip 提示
+- 将示例中的 `http://127.0.0.1:8000` 替换为你的实际服务地址
+- 将 `a3541c2f0d3e1b4a5c6d7e8f9a0b1c2d3e` 替换为你在管理后台创建的实际 Token
+- 建议在生产环境中使用 HTTPS
+:::
@@ -0,0 +1,106 @@
+# API 使用说明
+
+Message Nest 提供统一的消息推送API接口。
+
+## 接口地址
+
+```
+POST /api/v1/message/send
+```
+
+## 请求参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| token | string | 是 | 推送令牌，在管理后台查看 |
+| title | string | 是 | 消息标题 |
+| text | string | 是 | 消息内容 |
+
+## 请求示例
+
+```json
+{
+    "token": "a3541c2f0d3e1b4a5c6d7e8f9a0b1c2d3e",
+    "title": "message title",
+    "text": "Hello World!"
+}
+```
+
+## 响应格式
+
+### 成功响应
+
+```json
+{
+    "code": 200,
+    "msg": "success",
+    "data": {
+        "status": "sent"
+    }
+}
+```
+
+### 失败响应
+
+```json
+{
+    "code": 400,
+    "msg": "error message",
+    "data": null
+}
+```
+
+## 获取 Token
+
+1. 登录 Message Nest 管理后台
+2. 进入"发送任务"页面
+3. 创建新的发送任务
+4. 配置推送渠道（邮件、钉钉、企业微信等）
+5. 保存后获得推送令牌（Token）
+
+## 支持的推送渠道
+
+- **邮件** - SMTP邮件发送
+- **钉钉** - 钉钉机器人
+- **企业微信** - 企业微信应用消息
+- **微信公众号** - 微信测试公众号模板消息
+- **自定义Webhook** - 自定义HTTP请求
+- **自托管消息** - 站内消息
+
+## 使用流程
+
+1. **创建推送渠道**
+   - 在管理后台配置各种推送渠道
+   - 填写相应的配置信息（如邮箱、Webhook地址等）
+
+2. **创建发送任务**
+   - 选择要使用的推送渠道
+   - 可以选择多个渠道同时推送
+   - 获得唯一的推送令牌（Token）
+
+3. **调用API发送消息**
+   - 使用获得的 Token
+   - 发送标题和内容
+   - 消息会自动推送到配置的所有渠道
+
+## 注意事项
+
+::: warning 重要
+- Token 是唯一的，请妥善保管
+- 消息内容支持纯文本和Markdown格式（取决于推送渠道）
+- 建议使用异步方式调用API，避免阻塞主流程
+:::
+
+## 错误码说明
+
+| 错误码 | 说明 |
+|--------|------|
+| 200 | 成功 |
+| 400 | 请求参数错误 |
+| 401 | 未授权 |
+| 404 | Token不存在 |
+| 500 | 服务器内部错误 |
+
+## 下一步
+
+查看各语言的 [调用示例](/api/examples)。