KT知识库
MrDoc API 接口文档
KT企业知识库-重要信息
推荐ai工具
KT翻译软件推广方案-测试
KT翻译软件关键词列表
KT翻译软件竞品全面分析报告
本文档使用 MrDoc 发布
-
+
首页
MrDoc API 接口文档
# MrDoc API 接口文档 基于源码分析，MrDoc 提供了两套 API 系统： --- ## 快速开始：如何获取 Token MrDoc 提供两种方式获取 API Token，用于不同的 API 系统调用。 ### 方式一：通过账号密码自动获取（推荐） 使用 RESTful API 的登录接口，可以通过用户名和密码直接获取 Token，适合自动化场景。 **接口**: `/api/app/login/` **方法**: `POST` #### cURL 示例 ```bash curl -X POST "https://your-mrdoc-site.com/api/app/login/" \ -H "Content-Type: application/json" \ -d '{ "username": "your_username", "password": "your_password" }' ``` #### Python 示例 ```python import requests response = requests.post( 'https://your-mrdoc-site.com/api/app/login/', json={ 'username': 'your_username', 'password': 'your_password' } ) result = response.json() if result['code'] == 0: token = result['token'] print(f"获取到的 Token: {token}") # 使用 Token 调用 API headers = {'Authorization': f'Token {token}'} projects = requests.get( 'https://your-mrdoc-site.com/api/app/projects/?range=self', headers=headers ) print(projects.json()) ``` #### 响应示例 ```json { "code": 0, "token": "a1b2c3d4e5f6g7h8i9j0...", "username": "your_username" } ``` **注意**：此方式获取的 Token 用于 **RESTful API**（`/api/app/` 路径），需要在 HTTP Header 中传递： ``` Authorization: Token YOUR_TOKEN ``` --- ### 方式二：通过网页手动生成 登录 MrDoc 网站后，在个人中心生成 Token，适合手动配置的场景。 **步骤**： 1. 登录 MrDoc 系统 2. 进入「个人中心」 3. 点击「Token 管理」 4. 点击生成按钮获取 Token **注意**：此方式获取的 Token 用于 **Token API**（`/api/` 路径），需要在 URL 参数中传递： ``` /api/get_projects/?token=YOUR_TOKEN ``` --- ### 两种 Token 的区别 | 特性 | RESTful API Token | Token API Token | |------|------------------|----------------| | **获取方式** | `/api/app/login/` 接口 | 网页个人中心生成 | | **使用场景** | 自动化、第三方集成 | 手动配置、简单调用 | | **使用路径** | `/api/app/*` | `/api/*` | | **传递方式** | HTTP Header<br/>`Authorization: Token xxx` | URL 参数<br/>`?token=xxx` | | **数据库表** | `AppUserToken` | `UserToken` | | **Token 格式** | MD5 哈希值 | SHA224 哈希值 | **推荐**：对于需要自动化集成的场景，建议使用**方式一（RESTful API）**，因为可以通过接口自动获取和刷新 Token。 --- ## 一、基于 Token 的 API（推荐用于第三方集成） **Base URL**: `/api/` **认证方式**: URL 参数传递 Token (`?token=YOUR_TOKEN`) ### 1. Token 管理 #### 1.1 生成/管理 Token - **接口**: `/api/manage_token/` - **方法**: `GET`, `POST` - **权限**: 需登录 - **说明**: - GET: 查看当前 Token - POST: 生成新 Token（会覆盖旧 Token） - **响应**: ```json { "status": true, "data": "生成的token字符串" } ``` #### 1.2 验证 Token - **接口**: `/api/check_token/` - **方法**: `GET` - **参数**: `token` (必填) - **响应**: ```json { "status": true, "data": { "is_writer": true, "username": "用户昵称", "user_type": "admin|user" } } ``` --- ### 2. 文集管理 #### 2.1 获取文集列表 - **接口**: `/api/get_projects/` - **方法**: `GET` - **参数**: - `token` (必填) - `sort_name` (可选): 排序字段，默认 `create_time` - `sort` (可选): `0`=升序, `1`=降序 - `filter_name` (可选): `self`=自己的文集, `colla`=协作的文集 - `kw` (可选): 搜索关键词 - **响应**: ```json { "status": true, "data": [ { "id": 1, "name": "文集名称", "icon": "图标", "type": 0, "desc": "文集简介", "total": 10, "create_time": "2023-01-01 00:00:00" } ] } ``` #### 2.2 获取指定文集信息 - **接口**: `/api/get_project/` - **方法**: `GET` - **参数**: - `token` (必填) - `pid` (必填): 文集ID - **响应**: 返回文集详细信息 #### 2.3 创建文集 - **接口**: `/api/create_project/` - **方法**: `POST` - **参数**: - `token` (必填) - `name` (必填): 文集名称 - `desc` (可选): 文集简介 - `role` (可选): 权限，默认1 - **Content-Type**: 支持 `application/json` 或 `application/x-www-form-urlencoded` - **响应**: ```json { "status": true, "data": 新建文集的ID } ``` --- ### 3. 文档管理 #### 3.1 获取文集的文档列表（分页） - **接口**: `/api/get_docs/` - **方法**: `GET` - **参数**: - `token` (必填) - `pid` (必填): 文集ID - `sort` (可选): `0`=升序, `1`=降序 - `limit` (可选): 每页数量，默认10 - `page` (可选): 页码，默认1 - **响应**: ```json { "status": true, "data": [ { "id": 1, "name": "文档名称", "parent_doc": 0, "top_doc": 1, "status": 1, "create_time": "2023-01-01", "modify_time": "2023-01-01", "create_user": "username", "editor_mode": 1 } ] } ``` #### 3.2 获取文集的层级文档列表 - **接口**: `/api/get_level_docs/` - **方法**: `GET` - **参数**: - `token` (必填) - `pid` (必填): 文集ID - **说明**: 返回三级树形结构的文档列表 - **响应**: ```json { "status": true, "data": [ { "id": 1, "name": "一级文档", "editor_mode": 1, "parent_doc": 0, "top_doc": 1, "sub": [ { "id": 2, "name": "二级文档", "sub": [] } ] } ], "total": 10 } ``` #### 3.3 获取个人文档列表 - **接口**: `/api/get_self_docs/` - **方法**: `GET` - **参数**: - `token` (必填) - `sort` (可选): `0`=升序, `1`=降序 - `kw` (可选): 搜索关键词 - `limit` (可选): 每页数量，默认10 - `page` (可选): 页码 - **响应**: 返回用户所有文档列表（按修改时间排序） #### 3.4 获取单篇文档 - **接口**: `/api/get_doc/` - **方法**: `GET` - **参数**: - `token` (必填) - `did` (必填): 文档ID - **响应**: ```json { "status": true, "data": { "id": 1, "name": "文档名称", "content": "HTML内容", "md_content": "Markdown内容", "parent_doc": 0, "top_doc": 1, "project_name": "文集名称", "status": 1, "editor_mode": 1, "create_time": "2023-01-01", "modify_time": "2023-01-01", "create_user": "username" } } ``` #### 3.5 获取文档上下篇 - **接口**: `/api/get_doc_previous_next/` - **方法**: `GET` - **参数**: - `token` (必填) - `did` (必填): 文档ID - **响应**: ```json { "status": true, "data": { "next": 3, "previous": 1 } } ``` #### 3.6 创建文档 - **接口**: `/api/create_doc/` - **方法**: `POST` - **参数**: - `token` (必填) - `pid` (必填): 文集ID - `title` (必填): 文档标题 - `doc` (必填): 文档内容 - `parent_doc` (可选): 上级文档ID，默认0 - `editor_mode` (可选): 编辑器模式，`1`=Markdown, `2`=Vditor, `3`=富文本 - **Content-Type**: 支持 `application/json` 或 `application/x-www-form-urlencoded` - **响应**: ```json { "status": true, "data": 新建文档的ID } ``` #### 3.7 修改文档 - **接口**: `/api/modify_doc/` - **方法**: `POST` - **参数**: - `token` (必填) - `pid` (必填): 文集ID - `did` (必填): 文档ID - `title` (必填): 文档标题 - `doc` (必填): 文档内容 - `parent_doc` (可选): 上级文档ID - **Content-Type**: 支持 `application/json` 或 `application/x-www-form-urlencoded` - **响应**: ```json { "status": true, "data": "ok" } ``` #### 3.8 删除文档（软删除） - **接口**: `/api/delete_doc/` - **方法**: `POST` - **参数**: - `token` (必填) - `did` (必填): 文档ID - **Content-Type**: 支持 `application/json` 或 `application/x-www-form-urlencoded` - **响应**: ```json { "status": true, "data": "ok" } ``` --- ### 4. 图片上传 #### 4.1 上传图片 - **接口**: `/api/upload_img/` - **方法**: `POST` - **参数**: - `token` (必填) - `base64` (可选): Base64编码的图片 - `image` (可选): 普通图片文件 - **Content-Type**: 支持 `application/json` 或 `multipart/form-data` - **响应**: ```json { "success": 1, "url": "图片URL" } ``` #### 4.2 上传URL图片 - **接口**: `/api/upload_img_url/` - **方法**: `POST` - **参数**: - `token` (必填) - `url` (必填): 图片URL或Base64 - **响应**: ```json { "success": 1, "url": "图片URL" } ``` --- ### 5. 搜索功能 MrDoc 的搜索功能集成在文集和文档的列表接口中，通过 `kw` 参数实现关键词搜索。 #### 5.1 搜索文集 - **接口**: `/api/get_projects/` - **方法**: `GET` - **参数**: - `token` (必填) - `kw` (必填): 搜索关键词，支持文集名称和简介搜索 - `sort` (可选): `0`=升序, `1`=降序 - `sort_name` (可选): 排序字段 - `filter_name` (可选): `self`=自己的文集, `colla`=协作的文集 - **搜索范围**: 文集名称（`name`）和文集简介（`intro`） - **示例**: ```bash # 搜索包含"API"关键词的文集 curl "https://your-mrdoc-site.com/api/get_projects/?token=YOUR_TOKEN&kw=API" ``` - **响应**: ```json { "status": true, "data": [ { "id": 1, "name": "API 开发文档", "icon": "", "type": 0, "desc": "API 接口说明", "total": 10, "create_time": "2023-01-01 00:00:00" } ] } ``` #### 5.2 搜索个人文档 - **接口**: `/api/get_self_docs/` - **方法**: `GET` - **参数**: - `token` (必填) - `kw` (必填): 搜索关键词，支持文档标题搜索 - `sort` (可选): `0`=升序, `1`=降序 - `limit` (可选): 每页数量，默认10 - `page` (可选): 页码 - **搜索范围**: 文档标题（`name`） - **排序方式**: 按文档修改时间排序 - **示例**: ```bash # 搜索标题包含"接口"的文档 curl "https://your-mrdoc-site.com/api/get_self_docs/?token=YOUR_TOKEN&kw=接口&limit=20" ``` - **响应**: ```json { "status": true, "data": [ { "id": 1, "name": "接口文档", "summary": "文档摘要...", "parent_doc": 0, "top_doc": 1, "project_name": "API文集", "project_role": 0, "project_icon": "", "editor_mode": 1, "status": 1, "create_time": "2023-01-01", "modify_time": "2023-01-02", "create_user": "admin" } ] } ``` #### 5.3 Python 搜索示例 ```python import requests base_url = 'https://your-mrdoc-site.com' token = 'YOUR_TOKEN' # 搜索文集 search_keyword = 'API' response = requests.get( f'{base_url}/api/get_projects/', params={ 'token': token, 'kw': search_keyword, 'sort': '1' # 降序 } ) projects = response.json() print(f"找到 {len(projects['data'])} 个文集") # 搜索文档 doc_keyword = '接口' response = requests.get( f'{base_url}/api/get_self_docs/', params={ 'token': token, 'kw': doc_keyword, 'limit': 50, 'page': 1 } ) docs = response.json() print(f"找到的文档:") for doc in docs['data']: print(f" - {doc['name']} (文集: {doc['project_name']})") ``` --- ### 6. 辅助接口 #### 6.1 获取服务器时间戳 - **接口**: `/api/get_timestamp/` - **方法**: `GET` - **说明**: 用于生成 OAuth 请求的时间戳 - **响应**: ```json { "status": true, "data": "1234567890" } ``` #### 6.2 OAuth 登录 - **接口**: `/api/oauth0/` - **方法**: `GET` - **参数**: - `username` (必填) - `timestamp` (必填) - `randstr` (必填) - `hashstr` (必填): MD5(randstr + timestamp + username + token) - `redirecturl` (可选): 登录后跳转URL - **说明**: 通过 Token 实现单点登录 --- ## 二、RESTful API（基于 Django REST Framework） **Base URL**: `/api/app/` **认证方式**: Token Header (`Authorization: Token YOUR_TOKEN`) ### 1. 认证 #### 1.1 登录获取 Token - **接口**: `/api/app/login/` - **方法**: `POST` - **参数**: ```json { "username": "用户名", "password": "密码" } ``` - **响应**: ```json { "code": 0, "token": "生成的token", "username": "用户名" } ``` --- ### 2. 文集 API #### 2.1 获取文集列表/详情 - **接口**: `/api/app/projects/` - **方法**: `GET` - **参数**: - `id` (可选): 文集ID，获取指定文集 - `range` (可选): `self`=获取自己的文集 - `kw` (可选): 搜索关键词 - `sort` (可选): `0`=升序, `1`=降序 - `role` (可选): 筛选权限 `0`=公开, `1`=私密, `2`=指定用户, `3`=访问码, `99`=协作 - **响应**: ```json { "code": 0, "data": [...], "count": 10 } ``` #### 2.2 创建文集 - **接口**: `/api/app/projects/` - **方法**: `POST` - **参数**: ```json { "pname": "文集名称", "desc": "文集简介", "role": 0 } ``` - **响应**: ```json { "code": 0, "data": { "id": 1, "name": "文集名称" } } ``` #### 2.3 修改文集 - **接口**: `/api/app/projects/?id=文集ID` - **方法**: `PUT` - **参数**: ```json { "name": "文集名称", "desc": "文集简介", "role": 0, "role_value": "权限值" } ``` #### 2.4 删除文集 - **接口**: `/api/app/projects/?id=文集ID` - **方法**: `DELETE` --- ### 3. 文档 API #### 3.1 获取文档列表/详情 - **接口**: `/api/app/docs/` - **方法**: `GET` - **参数**: - `pid` (可选): 文集ID - `did` (可选): 文档ID - `type` (可选): `json` 或 `html` - **响应**: ```json { "code": 0, "data": {...}, "count": 10 } ``` #### 3.2 创建文档 - **接口**: `/api/app/docs/` - **方法**: `POST` - **参数**: ```json { "project": "文集ID", "parent_doc": "上级文档ID", "doc_name": "文档名称", "content": "HTML内容", "pre_content": "Markdown内容", "sort": 99, "status": 1 } ``` #### 3.3 修改文档 - **接口**: `/api/app/docs/` - **方法**: `PUT` - **参数**: ```json { "doc_id": "文档ID", "project": "文集ID", "parent_doc": "上级文档ID", "doc_name": "文档名称", "content": "HTML内容", "pre_content": "Markdown内容", "sort": 99, "status": 1 } ``` #### 3.4 删除文档 - **接口**: `/api/app/docs/` - **方法**: `DELETE` - **参数**: ```json { "doc_id": "文档ID" } ``` --- ### 4. 文档模板 API #### 4.1 获取模板列表/详情 - **接口**: `/api/app/doctemps/` - **方法**: `GET` - **参数**: `id` (可选): 模板ID #### 4.2 创建模板 - **接口**: `/api/app/doctemps/` - **方法**: `POST` - **参数**: ```json { "name": "模板名称", "content": "模板内容" } ``` #### 4.3 修改模板 - **接口**: `/api/app/doctemps/` - **方法**: `PUT` - **参数**: ```json { "doctemp_id": "模板ID", "name": "模板名称", "content": "模板内容" } ``` #### 4.4 删除模板 - **接口**: `/api/app/doctemps/` - **方法**: `DELETE` - **参数**: ```json { "doctemp_id": "模板ID" } ``` --- ### 5. 图片 API #### 5.1 获取图片列表 - **接口**: `/api/app/images/` - **方法**: `GET` - **参数**: `group` (可选): 分组ID，`0`=全部，`-1`=未分组 #### 5.2 上传图片 - **接口**: `/api/app/images/` - **方法**: `POST` - **参数**: - `api_img_upload`: 图片文件 - `dirname`: 目录名 - `base`: Base64编码图片 #### 5.3 删除图片 - **接口**: `/api/app/images/` - **方法**: `DELETE` - **参数**: ```json { "id": "图片ID" } ``` --- ### 6. 图片分组 API #### 6.1 获取分组列表 - **接口**: `/api/app/imggroups/` - **方法**: `GET` #### 6.2 创建分组 - **接口**: `/api/app/imggroups/` - **方法**: `POST` - **参数**: ```json { "group_name": "分组名称" } ``` #### 6.3 修改分组 - **接口**: `/api/app/imggroups/` - **方法**: `PUT` - **参数**: ```json { "group_id": "分组ID", "group_name": "分组名称" } ``` #### 6.4 删除分组 - **接口**: `/api/app/imggroups/` - **方法**: `DELETE` - **参数**: ```json { "group_id": "分组ID" } ``` --- ### 7. 搜索功能 RESTful API 的搜索功能同样集成在列表接口中，通过 `kw` 参数实现。 #### 7.1 搜索文集 - **接口**: `/api/app/projects/` - **方法**: `GET` - **认证**: 需要 Token 认证 - **参数**: - `kw` (必填): 搜索关键词 - `sort` (可选): `0`=升序, `1`=降序 - `role` (可选): 筛选权限类型 - **搜索范围**: 文集名称（`name`）和文集简介（`intro`） - **示例**: ```python import requests headers = {'Authorization': 'Token YOUR_TOKEN'} response = requests.get( 'https://your-mrdoc-site.com/api/app/projects/', params={'kw': 'API', 'sort': '1'}, headers=headers ) print(response.json()) ``` - **响应**: ```json { "code": 0, "data": [ { "id": 1, "name": "API文集", "intro": "API接口文档", "role": 0, "create_time": "2023-01-01" } ], "count": 1 } ``` #### 7.2 cURL 搜索示例 ```bash # 搜索文集 curl -X GET "https://your-mrdoc-site.com/api/app/projects/?kw=API" \ -H "Authorization: Token YOUR_TOKEN" # 搜索并筛选公开文集 curl -X GET "https://your-mrdoc-site.com/api/app/projects/?kw=文档&role=0" \ -H "Authorization: Token YOUR_TOKEN" ``` --- ### 8. 附件 API #### 8.1 获取附件列表 - **接口**: `/api/app/attachments/` - **方法**: `GET` #### 8.2 上传附件 - **接口**: `/api/app/attachments/` - **方法**: `POST` - **参数**: `attachment_upload`: 附件文件 - **限制**: 仅支持 ZIP 格式，最大 50MB #### 8.3 删除附件 - **接口**: `/api/app/attachments/` - **方法**: `DELETE` - **参数**: ```json { "attach_id": "附件ID" } ``` --- ## 状态码说明 ### Token API 状态码 - `status: true` - 成功 - `status: false` - 失败 ### RESTful API 状态码 - `0` - 成功 - `1` - 资源未找到 - `2` - 无权访问 - `3` - 需要访问码 - `4` - 系统异常 - `5` - 参数不正确 - `6` - 需要登录 --- ## 使用示例 ### Python 示例（Token API） ```python import requests base_url = 'https://your-mrdoc-site.com' token = 'YOUR_TOKEN' # 获取文集列表 response = requests.get(f'{base_url}/api/get_projects/?token={token}') print(response.json()) # 创建文档 data = { 'pid': 1, 'title': '新文档', 'doc': '# 文档内容', 'editor_mode': 1 } response = requests.post(f'{base_url}/api/create_doc/?token={token}', json=data) print(response.json()) # 上传图片（Base64） import base64 with open('image.png', 'rb') as f: img_base64 = f'data:image/png;base64,{base64.b64encode(f.read()).decode()}' response = requests.post( f'{base_url}/api/upload_img/?token={token}', json={'base64': img_base64} ) print(response.json()) ``` ### Python 示例（RESTful API） ```python import requests base_url = 'https://your-mrdoc-site.com/api/app' # 登录获取 Token login_data = {'username': 'user', 'password': 'pass'} response = requests.post(f'{base_url}/login/', json=login_data) token = response.json()['token'] # 使用 Token 获取文集列表 headers = {'Authorization': f'Token {token}'} response = requests.get(f'{base_url}/projects/?range=self', headers=headers) print(response.json()) # 创建文档 doc_data = { 'project': '1', 'doc_name': '新文档', 'content': '<p>HTML内容</p>', 'pre_content': '# Markdown内容' } response = requests.post(f'{base_url}/docs/', json=doc_data, headers=headers) print(response.json()) ``` ### JavaScript 示例（Token API） ```javascript const baseUrl = 'https://your-mrdoc-site.com'; const token = 'YOUR_TOKEN'; // 获取文集列表 fetch(`${baseUrl}/api/get_projects/?token=${token}`) .then(res => res.json()) .then(data => console.log(data)); // 创建文档 fetch(`${baseUrl}/api/create_doc/?token=${token}`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ pid: 1, title: '新文档', doc: '# 文档内容', editor_mode: 1 }) }) .then(res => res.json()) .then(data => console.log(data)); ``` ### cURL 示例 ```bash # 获取文集列表 curl "https://your-mrdoc-site.com/api/get_projects/?token=YOUR_TOKEN" # 创建文档 curl -X POST "https://your-mrdoc-site.com/api/create_doc/?token=YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "pid": 1, "title": "新文档", "doc": "# 文档内容", "editor_mode": 1 }' # RESTful API 登录 curl -X POST "https://your-mrdoc-site.com/api/app/login/" \ -H "Content-Type: application/json" \ -d '{ "username": "user", "password": "pass" }' ``` --- ## 注意事项 1. **Token 获取**: - Token API: 登录后在「个人中心」->「Token管理」生成 - RESTful API: 通过 `/api/app/login/` 接口使用账号密码获取 2. **编辑器模式**: `1`=Editor.md, `2`=Vditor, `3`=富文本, `4`=表格 3. **文集权限**: `0`=公开, `1`=私密, `2`=指定用户, `3`=访问码 4. **文档状态**: `1`=正常, `3`=已删除 5. **分页**: RESTful API 支持标准 DRF 分页参数 6. **CSRF**: Token API 已豁免 CSRF 验证 7. **文档层级**: 最多支持三级文档结构 8. **图片上传**: 支持 Base64 和文件两种方式 9. **附件限制**: 仅支持 ZIP 格式，最大 50MB 10. **时间格式**: 返回的时间字段为字符串格式 11. **搜索功能**: - 搜索使用 `kw` 参数，支持模糊匹配 - Token API: 搜索文集（`get_projects`）和文档（`get_self_docs`） - RESTful API: 搜索文集（`projects`） - 搜索范围: 文集支持名称和简介搜索，文档支持标题搜索 - 搜索结果可配合排序和分页参数使用 --- ## 源码参考 - Token API 实现: `app_api/views.py` - RESTful API 实现: `app_api/views_app.py` - URL 路由配置: `app_api/urls.py`, `app_api/urls_app.py` - GitHub 仓库: https://github.com/zmister2016/MrDoc - Gitee 仓库: https://gitee.com/zmister/MrDoc --- **文档版本**: 基于 MrDoc master 分支最新代码 **更新日期**: 2025-10-04
admin
2025年10月4日 22:04
转发文档
收藏文档
上一篇
下一篇
手机扫码
复制链接
手机扫一扫转发分享
复制链接
Markdown文件
PDF文档（打印）
分享
链接
类型
密码
更新密码