whz/paopao
1
0
Fork 0
Code Issues 18 Pull Requests Actions Packages Projects Releases Wiki Activity

[add] api docs

Browse Source
This commit is contained in:
whz 2024-05-17 10:55:30 +08:00
parent 1b237e542e
commit ec7096e663
4 changed files with 383 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
docs/API接口说明模板.md
View File

@ -1,29 +1,29 @@
# RESTFul API 文档 v1.0
# RESTFul API 文档 v0
## 1. 用户注册
## 用户注册
### 1.1 接口描述
### 1 接口描述
本API允许用户通过手机号或邮箱地址创建新账户。确保每个手机号或邮箱仅关联一个唯一账户。
### 1.2 请求URL
### 2 请求URL
`/api/user/signup`
### 1.3 请求方式
### 3 请求方式
**POST**
### 1.4 请求头
### 4 请求头
| 头字段 | 必填 | 数据类型 | 描述 |
| ------------ | ---- | ------------- | -------------------------------- |
| Content-Type | 是 | application/json | 指定请求体的媒体类型为JSON |
### 1.5 请求体参数
### 5 请求体参数
| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 | 示例 | 允许空值 |
|-----------| ---- | -------- | -------- | ---------------------------- | ------------ | -------- |
| account | 是 | 字符串 | 1-50字符 | 用于登录的账号（手机号或邮箱） | "user123" | 否 |
| password | 是 | 字符串 | 1-50字符 | 密码 | "p@ssw0rd" | 否 |
| checkCode | 是 | 字符串 | 6位数字 | 注册时收到的验证码 | "123456" | 否 |
### 1.6 请求示例
### 6 请求示例
```http
POST /api/user/signup
Host: {apiAddress}
@ -36,15 +36,15 @@ Content-Type: application/json
}
```
### 1.7 返回参数说明
### 7 返回参数说明
| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 |
|-----------| ---- | -------- | -------- | ---------------------------- |
|------| ---- | -------- | -------- | ---------------------------- |
| code | 是 | 整型 | | 错误码，200表示成功 |
| message | 否 | 字符串 | 1-50字符 | 错误信息描述 |
| msg | 否 | 字符串 | 1-50字符 | 错误信息描述 |
| data | 否 | json | | 具体业务数据 |
### 1.8 响应示例（成功）
### 8 响应示例（成功）
```json
{
@ -56,31 +56,31 @@ Content-Type: application/json
}
}
```
### 1.9 响应示例（错误）
### 9 响应示例（错误）
```json
{ "code": 10001, "message": "验证码无效" }
```
### 1.10 错误响应码参考
### 10 错误响应码参考
更多响应错误码及含义，请参阅[API响应码表](URL/for/api/responseCode/table)。
### 1.11 安全性与认证
### 11 安全性与认证
此API要求调用方在`Authorization`头中携带经过Bearer认证的令牌。
### 1.12 测试环境
### 12 测试环境
访问测试环境以进行接口调试：
[https://test.apiAddress.com](https://test.apiAddress.com)
### 1.13 版本管理
### 13 版本管理
本API通过URI路径进行版本控制。请在请求URL中包含`/v1`以使用当前版本。
### 1.14 更新记录
### 14 更新记录
- **2024-04-22**：发布文档初始版本。
- **2024-05-05**：新增安全性说明和测试环境链接。
### 1.15 联系支持
### 15 联系支持
如需帮助或对API有任何疑问，请通过电子邮件与我们联系：[support@api.com](mailto:support@api.com)。
### 1.16 反馈与建议
### 16 反馈与建议
发现文档问题或有改进建议？请填写[反馈表单](https://forms.api.com/feedback)与我们分享。

201
docs/api doc/发布动态.md Normal file
View File

@ -0,0 +1,201 @@
## 1. 发布动态接口
### 1.1 接口描述
用户发布动态。 动态支持图片、文字、话题、@等功能。
### 1.2 请求URL
`/v1/post`
### 1.3 请求方式
**POST**
### 1.4 请求头
| 头字段 | 必填 | 数据类型 | 描述 |
| ------------ | ---- | ------------- | -------------------------------- |
| Content-Type | 是 | application/json | 指定请求体的媒体类型为JSON |
### 1.5 请求体参数
| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 | 示例 | 允许空值 |
|-----------| ---- | -------- |--------| ---------------------------- | ----------- | -------- |
| | | | | | | |
| | | | | | | |
### 1.6 请求示例
```http
POST /v1/auth/login
Host: {apiAddress}
Content-Type: application/json
{
"contents": [
{
"content": "@ddd @mike #PAOPAO #J2EE #travel nice !!",
"type": 2,
"sort": 100
},
{
"content": "http://60.204.241.255:8008/oss/paopao/public/image/a2/6c/98/b8/17f2-4508-b7ed-57be788958ee.jpeg",
"type": 3,
"sort": 101
},
{
"content": "http://60.204.241.255:8008/oss/paopao/public/image/e6/58/3f/52/6d00-48de-ad48-1010a6e602ce.jpeg",
"type": 3,
"sort": 102
},
{
"content": "http://60.204.241.255:8008/oss/paopao/attachment/6a/e0/ee/73/6ec8-457a-b889-dc524c3c7f22.zip",
"type": 7,
"sort": 103
},
{
"content": "http://baidu.com",
"type": 6,
"sort": 104
},
{
"content": "http://taobao.com",
"type": 6,
"sort": 105
}
],
"tags": [
"PAOPAO",
"J2EE",
"travel"
],
"users": [
"ddd",
"mike"
],
"attachment_price": 800,
"visibility": 2
}
```
### 1.7 返回参数说明
| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 |
|------| ---- | -------- | -- |-----------|
| code | 是 | 整型 | | 错误码，0表示成功 |
| msg | 否 | 字符串 | | 错误信息描述 |
| data | 否 | json | | 具体业务数据 |
data结构说明：
| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 |
|-------| ---- | -------- |------|-----------|
| | | | | |
### 1.8 响应示例（成功）
```json
{
"code": 0,
"msg": "success",
"data": {
"id": 1080017998,
"user_id": 100066,
"user": {
"id": 100066,
"nickname": "xyz",
"username": "xyz",
"status": 1,
"avatar": "https://assets.paopao.info/public/avatar/default/jackson.png",
"is_admin": false,
"is_friend": false,
"is_following": false
},
"contents": [
{
"id": 180022562,
"post_id": 1080017998,
"content": "@ddd @mike #PAOPAO #J2EE #travel nice !!",
"type": 2,
"sort": 100
},
{
"id": 180022563,
"post_id": 1080017998,
"content": "http://60.204.241.255:8008/oss/paopao/public/image/a2/6c/98/b8/17f2-4508-b7ed-57be788958ee.jpeg",
"type": 3,
"sort": 101
},
{
"id": 180022564,
"post_id": 1080017998,
"content": "http://60.204.241.255:8008/oss/paopao/public/image/e6/58/3f/52/6d00-48de-ad48-1010a6e602ce.jpeg",
"type": 3,
"sort": 102
},
{
"id": 180022565,
"post_id": 1080017998,
"content": "http://60.204.241.255:8008/oss/paopao/attachment/6a/e0/ee/73/6ec8-457a-b889-dc524c3c7f22.zip",
"type": 8,
"sort": 103
},
{
"id": 180022566,
"post_id": 1080017998,
"content": "http://baidu.com",
"type": 6,
"sort": 104
},
{
"id": 180022567,
"post_id": 1080017998,
"content": "http://taobao.com",
"type": 6,
"sort": 105
}
],
"comment_count": 0,
"collection_count": 0,
"share_count": 0,
"upvote_count": 0,
"visibility": 50,
"is_top": 0,
"is_essence": 0,
"is_lock": 0,
"latest_replied_on": 1715913367,
"created_on": 1715913367,
"modified_on": 1715913367,
"tags": {
"J2EE": 1,
"PAOPAO": 1,
"travel": 1
},
"attachment_price": 800,
"ip_loc": "山东省临沂市"
}
}
```
### 1.9 响应示例（错误）
```json
{ "code": 401, "msg": "验证失败" }
```
### 1.10 错误响应码参考
更多响应错误码及含义，请参阅[API响应码表](URL/for/api/responseCode/table)。
### 1.11 安全性与认证
### 1.12 测试环境
访问测试环境以进行接口调试：
[https://test.apiAddress.com](https://test.apiAddress.com)
### 1.13 版本管理
本API通过URI路径进行版本控制。请在请求URL中包含`/v1`以使用当前版本。
### 1.14 更新记录
- **2024-04-29**：发布文档初始版本。
### 1.15 联系支持
如需帮助或对API有任何疑问，请通过电子邮件与我们联系：[support@api.com](mailto:support@api.com)。
### 1.16 反馈与建议
发现文档问题或有改进建议？请填写[反馈表单](https://forms.api.com/feedback)与我们分享。

82
docs/api doc/获得推荐用户接口.md Normal file
View File

@ -0,0 +1,82 @@
# RESTFul API 文档
## 获得推荐用户
### 1 接口描述
本API允许通过用户账号模糊匹配获得推荐用户。
### 2 请求URL
`/v1/suggest/users?k=`
### 3 请求方式
**GET**
### 4 请求头
| 头字段 | 必填 | 数据类型 | 描述 |
| ------------ | ---- | ------------- | -------------------------------- |
| | | ||
### 5 Query参数
| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 | 示例 | 允许空值 |
|-----------|----| -------- | ------- |-----------|------------|------|
| k | 否 | 字符串 | | 查询条件 | "wang" | 是 |
### 6 请求示例
```http
GET /v1/suggest/users?k=w
```
### 7 返回参数说明
| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 |
|------| ---- | -------- | -------- | ---------------------------- |
| code | 是 | 整型 | | 错误码，200表示成功 |
| msg | 否 | 字符串 | 1-50字符 | 错误信息描述 |
| data | 否 | json | | 具体业务数据 |
### 8 响应示例（成功）
```json
{
"code": 0,
"msg": "success",
"data": {
"suggest": [
"wangji",
"whj",
"whjwhj",
"whz",
"wu123",
"www"
]
}
}
```
### 9 响应示例（错误）
```json
{ "code": 10001, "message": "验证码无效" }
```
### 10 错误响应码参考
更多响应错误码及含义，请参阅[API响应码表](URL/for/api/responseCode/table)。
### 11 安全性与认证
此API要求调用方在`Authorization`头中携带经过Bearer认证的令牌。
### 12 测试环境
访问测试环境以进行接口调试：
[https://test.apiAddress.com](https://test.apiAddress.com)
### 13 版本管理
本API通过URI路径进行版本控制。请在请求URL中包含`/v1`以使用当前版本。
### 14 更新记录
- **2024-04-22**：发布文档初始版本。
- **2024-05-05**：新增安全性说明和测试环境链接。
### 15 联系支持
如需帮助或对API有任何疑问，请通过电子邮件与我们联系：[support@api.com](mailto:support@api.com)。
### 16 反馈与建议
发现文档问题或有改进建议？请填写[反馈表单](https://forms.api.com/feedback)与我们分享。

78
docs/api doc/获得推荐话题接口.md Normal file
View File

@ -0,0 +1,78 @@
# RESTFul API 文档
## 获得推荐话题
### 1 接口描述
本API允许通过话题模糊匹配获得推荐话题。
### 2 请求URL
`/v1/suggest/tags?k=`
### 3 请求方式
**GET**
### 4 请求头
| 头字段 | 必填 | 数据类型 | 描述 |
| ------------ | ---- | ------------- | -------------------------------- |
| | | ||
### 5 Query参数
| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 | 示例 | 允许空值 |
|-----------|----| -------- | ------- |-----------|-----|------|
| k | 否 | 字符串 | | 查询条件 | "P" | 是 |
### 6 请求示例
```http
GET /v1/suggest/tags?k=P
```
### 7 返回参数说明
| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 |
|------| ---- | -------- | -------- | ---------------------------- |
| code | 是 | 整型 | | 错误码，200表示成功 |
| msg | 否 | 字符串 | 1-50字符 | 错误信息描述 |
| data | 否 | json | | 具体业务数据 |
### 8 响应示例（成功）
```json
{
"code": 0,
"msg": "success",
"data": {
"suggest": [
"PAOPAO",
"Post"
]
}
}
```
### 9 响应示例（错误）
```json
{ "code": 10001, "message": "验证码无效" }
```
### 10 错误响应码参考
更多响应错误码及含义，请参阅[API响应码表](URL/for/api/responseCode/table)。
### 11 安全性与认证
此API要求调用方在`Authorization`头中携带经过Bearer认证的令牌。
### 12 测试环境
访问测试环境以进行接口调试：
[https://test.apiAddress.com](https://test.apiAddress.com)
### 13 版本管理
本API通过URI路径进行版本控制。请在请求URL中包含`/v1`以使用当前版本。
### 14 更新记录
- **2024-04-22**：发布文档初始版本。
- **2024-05-05**：新增安全性说明和测试环境链接。
### 15 联系支持
如需帮助或对API有任何疑问，请通过电子邮件与我们联系：[support@api.com](mailto:support@api.com)。
### 16 反馈与建议
发现文档问题或有改进建议？请填写[反馈表单](https://forms.api.com/feedback)与我们分享。