From ec7096e663dc2feba0d857bf6be8ddf7872e6a63 Mon Sep 17 00:00:00 2001 From: whz <303054730@qq.com> Date: Fri, 17 May 2024 10:55:30 +0800 Subject: [PATCH] [add] api docs --- docs/API接口说明模板.md | 44 +++---- docs/api doc/发布动态.md | 201 +++++++++++++++++++++++++++++++ docs/api doc/获得推荐用户接口.md | 82 +++++++++++++ docs/api doc/获得推荐话题接口.md | 78 ++++++++++++ 4 files changed, 383 insertions(+), 22 deletions(-) create mode 100644 docs/api doc/发布动态.md create mode 100644 docs/api doc/获得推荐用户接口.md create mode 100644 docs/api doc/获得推荐话题接口.md diff --git a/docs/API接口说明模板.md b/docs/API接口说明模板.md index c54e265..f069c9e 100644 --- a/docs/API接口说明模板.md +++ b/docs/API接口说明模板.md @@ -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 返回参数说明 -| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 | -|-----------| ---- | -------- | -------- | ---------------------------- | -| code | 是 | 整型 | | 错误码，200表示成功 | -| message | 否 | 字符串 | 1-50字符 | 错误信息描述 | +### 7 返回参数说明 +| 参数名称 | 必填 | 数据类型 | 约束条件 | 描述 | +|------| ---- | -------- | -------- | ---------------------------- | +| code | 是 | 整型 | | 错误码，200表示成功 | +| 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)与我们分享。 diff --git a/docs/api doc/发布动态.md b/docs/api doc/发布动态.md new file mode 100644 index 0000000..2ccd668 --- /dev/null +++ b/docs/api doc/发布动态.md @@ -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)与我们分享。 + diff --git a/docs/api doc/获得推荐用户接口.md b/docs/api doc/获得推荐用户接口.md new file mode 100644 index 0000000..742ffa6 --- /dev/null +++ b/docs/api doc/获得推荐用户接口.md @@ -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)与我们分享。 + diff --git a/docs/api doc/获得推荐话题接口.md b/docs/api doc/获得推荐话题接口.md new file mode 100644 index 0000000..2954eb0 --- /dev/null +++ b/docs/api doc/获得推荐话题接口.md @@ -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)与我们分享。 +