Skip to content

Commit 61948c7

Browse files
RabithuaRabithua
committed
docs: fix API documentation response structures and paths
- Fix LOGIN-API.md: add missing user fields (description, avatar, cover, createdAt, updatedAt) - Fix REACTIONS-API.md: add complete note and reaction fields in response examples - Fix SEARCH-API.md: correct API paths from /api/v2 to /v2/api, add complete response structure - Fix USER-API.md: correct role field value from 'USER' to 'user', add complete note fields in export response - Ensure all documentation matches backend implementation
1 parent 35eddb7 commit 61948c7

4 files changed

Lines changed: 108 additions & 47 deletions

File tree

‎doc/userguide/LOGIN-API.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,12 @@ curl -X POST 'https://your-domain.com/v2/api/auth/login' \
4242
"username": "demo",
4343
"email": "demo@example.com",
4444
"nickname": "Demo",
45-
"role": "USER"
45+
"description": "用户简介",
46+
"avatar": "https://example.com/avatar.jpg",
47+
"cover": "https://example.com/cover.jpg",
48+
"role": "user",
49+
"createdAt": "2024-01-01T00:00:00.000Z",
50+
"updatedAt": "2024-01-01T00:00:00.000Z"
4651
},
4752
"accessToken": "<ACCESS_TOKEN>",
4853
"refreshToken": "<REFRESH_TOKEN>"

‎doc/userguide/REACTIONS-API.md‎

Lines changed: 29 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -179,24 +179,50 @@ curl -X DELETE 'https://your-domain.com/v2/api/reactions/<NOTE_ID>/%E2%9D%A4%EF%
179179
"message": "success",
180180
"data": {
181181
"id": "note-uuid",
182-
"content": "笔记内容",
183182
"title": "笔记标题",
183+
"type": "Rote",
184+
"tags": ["标签1"],
185+
"content": "笔记内容",
186+
"state": "public",
187+
"archived": false,
188+
"authorid": "user-uuid",
189+
"pin": false,
190+
"editor": "normal",
191+
"createdAt": "2024-01-01T00:00:00.000Z",
192+
"updatedAt": "2024-01-01T00:00:00.000Z",
193+
"author": {
194+
"username": "demo",
195+
"nickname": "演示用户",
196+
"avatar": "https://example.com/avatar.jpg"
197+
},
198+
"attachments": [],
184199
"reactions": [
185200
{
186201
"id": "reaction-uuid-1",
187202
"type": "👍",
188203
"roteid": "note-uuid",
189204
"userid": "user-uuid-1",
190205
"visitorId": null,
191-
"createdAt": "2024-01-01T12:00:00.000Z"
206+
"visitorInfo": null,
207+
"metadata": null,
208+
"createdAt": "2024-01-01T12:00:00.000Z",
209+
"updatedAt": "2024-01-01T12:00:00.000Z"
192210
},
193211
{
194212
"id": "reaction-uuid-2",
195213
"type": "❤️",
196214
"roteid": "note-uuid",
197215
"userid": null,
198216
"visitorId": "fp_1234567890abcdef",
199-
"createdAt": "2024-01-01T12:01:00.000Z"
217+
"visitorInfo": {
218+
"browser": "Chrome",
219+
"os": "macOS"
220+
},
221+
"metadata": {
222+
"source": "web"
223+
},
224+
"createdAt": "2024-01-01T12:01:00.000Z",
225+
"updatedAt": "2024-01-01T12:01:00.000Z"
200226
}
201227
]
202228
}

‎doc/userguide/SEARCH-API.md‎

Lines changed: 38 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
1-
# 搜索API文档
1+
# 搜索 API 文档
22

33
## 概述
44

5-
新增的关键词搜索API允许在用户的笔记中进行全文搜索，支持搜索标题、内容和标签。
5+
新增的关键词搜索 API 允许在用户的笔记中进行全文搜索，支持搜索标题、内容和标签。
66

7-
## API端点
7+
## API 端点
88

99
### 1. 搜索当前用户的笔记
1010

1111
```
12-
GET /api/v2/notes/search
12+
GET /v2/api/notes/search
1313
```
1414

1515
**认证要求**: 需要登录
@@ -18,7 +18,7 @@ GET /api/v2/notes/search
1818

1919
- `keyword` (必需): 搜索关键词
2020
- `skip` (可选): 跳过的笔记数量，用于分页
21-
- `limit` (可选): 返回的笔记数量限制，默认20
21+
- `limit` (可选): 返回的笔记数量限制，默认 20
2222
- `archived` (可选): 是否搜索已归档的笔记 (true/false)
2323
- `tag` (可选): 按标签过滤 (支持多个标签)
2424

@@ -36,14 +36,25 @@ GET /api/v2/notes/search
3636
"message": "success",
3737
"data": [
3838
{
39-
"id": "...",
40-
"title": "...",
41-
"content": "...",
42-
"tags": ["..."],
43-
"author": {...},
44-
"attachments": [...],
45-
"createdAt": "...",
46-
"updatedAt": "..."
39+
"id": "uuid",
40+
"title": "笔记标题",
41+
"type": "Rote",
42+
"tags": ["标签1"],
43+
"content": "笔记内容",
44+
"state": "public",
45+
"archived": false,
46+
"authorid": "user-uuid",
47+
"pin": false,
48+
"editor": "normal",
49+
"createdAt": "2024-01-01T00:00:00.000Z",
50+
"updatedAt": "2024-01-01T00:00:00.000Z",
51+
"author": {
52+
"username": "demo",
53+
"nickname": "演示用户",
54+
"avatar": "https://example.com/avatar.jpg"
55+
},
56+
"attachments": [],
57+
"reactions": []
4758
}
4859
]
4960
}
@@ -52,7 +63,7 @@ GET /api/v2/notes/search
5263
### 2. 搜索公开笔记
5364

5465
```
55-
GET /api/v2/notes/search/public
66+
GET /v2/api/notes/search/public
5667
```
5768

5869
**认证要求**: 无
@@ -61,15 +72,15 @@ GET /api/v2/notes/search/public
6172

6273
- `keyword` (必需): 搜索关键词
6374
- `skip` (可选): 跳过的笔记数量，用于分页
64-
- `limit` (可选): 返回的笔记数量限制，默认20
75+
- `limit` (可选): 返回的笔记数量限制，默认 20
6576
- `tag` (可选): 按标签过滤
6677

6778
**搜索范围**: 所有公开状态的笔记
6879

6980
### 3. 搜索指定用户的公开笔记
7081

7182
```
72-
GET /api/v2/notes/search/users/:username
83+
GET /v2/api/notes/search/users/:username
7384
```
7485

7586
**认证要求**: 无
@@ -82,29 +93,29 @@ GET /api/v2/notes/search/users/:username
8293

8394
- `keyword` (必需): 搜索关键词
8495
- `skip` (可选): 跳过的笔记数量，用于分页
85-
- `limit` (可选): 返回的笔记数量限制，默认20
96+
- `limit` (可选): 返回的笔记数量限制，默认 20
8697
- `archived` (可选): 是否搜索已归档的笔记
8798
- `tag` (可选): 按标签过滤
8899

89100
**搜索范围**: 指定用户的公开笔记
90101

91-
### 4. API密钥搜索
102+
### 4. API 密钥搜索
92103

93104
```
94-
GET /api/v2/openkey/notes/search
105+
GET /v2/api/openkey/notes/search
95106
```
96107

97-
**认证要求**: API密钥
108+
**认证要求**: API 密钥
98109

99110
**查询参数**:
100111

101112
- `keyword` (必需): 搜索关键词
102113
- `skip` (可选): 跳过的笔记数量，用于分页
103-
- `limit` (可选): 返回的笔记数量限制，默认20
114+
- `limit` (可选): 返回的笔记数量限制，默认 20
104115
- `archived` (可选): 是否搜索已归档的笔记
105116
- `tag` (可选): 按标签过滤
106117

107-
**搜索范围**: API密钥拥有者的所有笔记
118+
**搜索范围**: API 密钥拥有者的所有笔记
108119

109120
## 搜索特性
110121

@@ -116,7 +127,7 @@ GET /api/v2/openkey/notes/search
116127

117128
### 2. 逻辑组合
118129

119-
搜索使用OR逻辑，即关键词在标题、内容或标签中任一匹配即返回该笔记。
130+
搜索使用 OR 逻辑，即关键词在标题、内容或标签中任一匹配即返回该笔记。
120131

121132
### 3. 过滤组合
122133

@@ -136,19 +147,19 @@ GET /api/v2/openkey/notes/search
136147
### 搜索包含"React"的个人笔记
137148

138149
```bash
139-
GET /api/v2/notes/search?keyword=React&limit=10
150+
GET /v2/api/notes/search?keyword=React&limit=10
140151
```
141152

142153
### 搜索公开笔记中包含"JavaScript"且带有"教程"标签的笔记
143154

144155
```bash
145-
GET /api/v2/notes/search/public?keyword=JavaScript&tag=教程
156+
GET /v2/api/notes/search/public?keyword=JavaScript&tag=教程
146157
```
147158

148159
### 搜索用户"john"的公开笔记中包含"API"的内容
149160

150161
```bash
151-
GET /api/v2/notes/search/users/john?keyword=API
162+
GET /v2/api/notes/search/users/john?keyword=API
152163
```
153164

154165
## 错误响应
@@ -197,7 +208,7 @@ GET /api/v2/notes/search/users/john?keyword=API
197208
// 防抖搜索
198209
const debounceSearch = debounce(async (keyword) => {
199210
if (keyword.length >= 2) {
200-
const results = await get('/notes/search', { keyword });
211+
const results = await get("/notes/search", { keyword });
201212
setSearchResults(results.data);
202213
}
203214
}, 300);

0 commit comments

Comments
 (0)