mirror of
https://gitee.com/ulthon/ulthon_information.git
synced 2026-07-01 18:02:47 +08:00
0e3a442ddd
统一处理 publish_time 参数，空字符串按未传处理。在创建和更新文章时，当文章状态为发布且未提供 publish_time 时，自动填充当前时间。同时修复更新文章时，从草稿首次发布且原 publish_time 为 0 时自动填充时间的逻辑。
563 lines
24 KiB
HTML
563 lines
24 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<title>{$page_title}-{:get_system_config('site_name')}</title>
|
||
{include file='common/_require'/}
|
||
<style>
|
||
.api-doc-wrap {
|
||
background: #fff;
|
||
border-radius: 4px;
|
||
padding: 24px 28px;
|
||
line-height: 1.8;
|
||
color: #333;
|
||
font-size: 14px;
|
||
}
|
||
.api-doc-wrap h2 {
|
||
font-size: 20px;
|
||
font-weight: bold;
|
||
border-bottom: 2px solid #1E9FFF;
|
||
padding-bottom: 8px;
|
||
margin: 30px 0 16px;
|
||
color: #1E9FFF;
|
||
}
|
||
.api-doc-wrap h2:first-child {
|
||
margin-top: 0;
|
||
}
|
||
.api-doc-wrap h3 {
|
||
font-size: 16px;
|
||
font-weight: bold;
|
||
margin: 20px 0 10px;
|
||
color: #333;
|
||
}
|
||
.api-doc-wrap p {
|
||
margin: 6px 0;
|
||
}
|
||
.api-method {
|
||
display: inline-block;
|
||
padding: 2px 10px;
|
||
border-radius: 3px;
|
||
color: #fff;
|
||
font-size: 12px;
|
||
font-weight: bold;
|
||
vertical-align: middle;
|
||
margin-right: 6px;
|
||
}
|
||
.api-method-get {
|
||
background: #5FB878;
|
||
}
|
||
.api-method-post {
|
||
background: #FF5722;
|
||
}
|
||
.api-endpoint {
|
||
font-family: Consolas, 'Courier New', monospace;
|
||
font-size: 14px;
|
||
color: #333;
|
||
}
|
||
.api-section {
|
||
background: #fafafa;
|
||
border: 1px solid #e8e8e8;
|
||
border-radius: 4px;
|
||
padding: 16px 20px;
|
||
margin: 12px 0 20px;
|
||
}
|
||
.api-section h4 {
|
||
font-size: 14px;
|
||
font-weight: bold;
|
||
margin: 0 0 8px;
|
||
color: #666;
|
||
}
|
||
.api-code {
|
||
background: #282c34;
|
||
color: #abb2bf;
|
||
padding: 12px 16px;
|
||
border-radius: 4px;
|
||
font-family: Consolas, 'Courier New', monospace;
|
||
font-size: 13px;
|
||
line-height: 1.6;
|
||
overflow-x: auto;
|
||
white-space: pre;
|
||
margin: 8px 0;
|
||
}
|
||
.api-code .api-code-comment {
|
||
color: #5c6370;
|
||
font-style: italic;
|
||
}
|
||
.api-doc-wrap .layui-table {
|
||
margin: 8px 0;
|
||
}
|
||
.api-doc-wrap .layui-table th {
|
||
background: #f2f2f2;
|
||
font-weight: bold;
|
||
}
|
||
.permission-tag {
|
||
display: inline-block;
|
||
background: #FFB800;
|
||
color: #fff;
|
||
padding: 1px 8px;
|
||
border-radius: 3px;
|
||
font-size: 12px;
|
||
margin-left: 6px;
|
||
}
|
||
</style>
|
||
</head>
|
||
|
||
<body>
|
||
<div class="layui-container main-container">
|
||
<div class="layui-row layui-col-space12">
|
||
{include file='common/_left'/}
|
||
<div class="layui-col-md7">
|
||
<div class="main-container">
|
||
<div class="api-doc-wrap">
|
||
|
||
<h2>1. 概述</h2>
|
||
|
||
<p><strong>API 基础 URL：</strong><code>{域名}/index.php/api/</code></p>
|
||
|
||
<h3>认证方式</h3>
|
||
<p>所有 API 请求需在 Header 中携带 API Key，支持以下两种方式：</p>
|
||
<div class="api-code">Authorization: Bearer {api_key}
|
||
X-API-Key: {api_key}</div>
|
||
|
||
<h3>响应格式</h3>
|
||
<div class="api-code">{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"data": {}
|
||
}</div>
|
||
<table class="layui-table" lay-skin="line">
|
||
<thead>
|
||
<tr><th>字段</th><th>类型</th><th>说明</th></tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr><td>code</td><td>int</td><td>状态码：0=成功, 401=认证失败, 403=权限不足, 500=业务错误</td></tr>
|
||
<tr><td>msg</td><td>string</td><td>提示信息</td></tr>
|
||
<tr><td>data</td><td>object/array</td><td>返回数据</td></tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<h2>2. 权限说明</h2>
|
||
<p>每个 API Key 对应一组权限，由管理员在后台分配：</p>
|
||
<table class="layui-table" lay-skin="line">
|
||
<thead>
|
||
<tr><th>权限字段</th><th>值</th><th>说明</th></tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr><td>can_write_own</td><td>0 或 1</td><td>能否创建和编辑通过 API 创建的数据</td></tr>
|
||
<tr><td>can_write_other</td><td>0 或 1</td><td>能否编辑通过后台管理创建的数据</td></tr>
|
||
<tr><td>can_delete</td><td>0 / 1 / 2</td><td>0=不能删除, 1=仅删除 API 创建的数据, 2=可删除所有数据</td></tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<h3>权限组合示例</h3>
|
||
<table class="layui-table" lay-skin="line">
|
||
<thead>
|
||
<tr><th>组合</th><th>can_write_own</th><th>can_write_other</th><th>can_delete</th></tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr><td>只读</td><td>0</td><td>0</td><td>0</td></tr>
|
||
<tr><td>只管自己</td><td>1</td><td>0</td><td>1</td></tr>
|
||
<tr><td>全权限</td><td>1</td><td>1</td><td>2</td></tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<h2>3. 文章接口</h2>
|
||
|
||
<h3>GET /api/articles/index - 文章列表 <span class="permission-tag">所有有效 Key</span></h3>
|
||
<div class="api-section">
|
||
<h4>请求参数</h4>
|
||
<table class="layui-table" lay-skin="line">
|
||
<thead>
|
||
<tr><th>参数</th><th>类型</th><th>必填</th><th>说明</th></tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr><td>page</td><td>int</td><td>否</td><td>页码，默认 1</td></tr>
|
||
<tr><td>limit</td><td>int</td><td>否</td><td>每页数量，默认 15</td></tr>
|
||
<tr><td>type</td><td>string</td><td>否</td><td>文章类型</td></tr>
|
||
<tr><td>category_id</td><td>int</td><td>否</td><td>分类 ID</td></tr>
|
||
<tr><td>keyword</td><td>string</td><td>否</td><td>搜索关键词</td></tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<h4>请求示例</h4>
|
||
<div class="api-code">curl -X GET \
|
||
"https://example.com/index.php/api/articles/index?page=1&limit=10" \
|
||
-H "Authorization: Bearer your_api_key"</div>
|
||
|
||
<h4>返回示例</h4>
|
||
<div class="api-code">{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 1,
|
||
"title": "文章标题",
|
||
"content": "文章内容",
|
||
"content_type": "html",
|
||
"type": "1",
|
||
"status": 1,
|
||
"source": "api",
|
||
"create_time": 1700000000,
|
||
"update_time": 1700000000,
|
||
"categorys": [...],
|
||
"tags": [...]
|
||
}
|
||
],
|
||
"total": 100,
|
||
"page": 1
|
||
}
|
||
}</div>
|
||
</div>
|
||
|
||
<h3>GET /api/articles/read - 文章详情 <span class="permission-tag">所有有效 Key</span></h3>
|
||
<div class="api-section">
|
||
<h4>请求参数</h4>
|
||
<table class="layui-table" lay-skin="line">
|
||
<thead>
|
||
<tr><th>参数</th><th>类型</th><th>必填</th><th>说明</th></tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr><td>id</td><td>int</td><td>是</td><td>文章 ID</td></tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<h4>请求示例</h4>
|
||
<div class="api-code">curl -X GET \
|
||
"https://example.com/index.php/api/articles/read?id=1" \
|
||
-H "Authorization: Bearer your_api_key"</div>
|
||
|
||
<h4>返回示例</h4>
|
||
<div class="api-code">{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"data": {
|
||
"post": {
|
||
"id": 1,
|
||
"title": "文章标题",
|
||
"content": "文章内容",
|
||
"content_html": "<p>HTML内容</p>",
|
||
"content_type": "html",
|
||
"desc": "摘要",
|
||
"poster": "/uploads/poster.jpg",
|
||
"type": "1",
|
||
"status": 1,
|
||
"source": "api"
|
||
},
|
||
"categories": [...],
|
||
"tags": [...]
|
||
}
|
||
}</div>
|
||
</div>
|
||
|
||
<h3>POST /api/articles/save - 创建文章 <span class="permission-tag" style="background:#FF5722;">can_write_own=1</span></h3>
|
||
<div class="api-section">
|
||
<p>Content-Type: <code>application/json</code></p>
|
||
<p>通过此接口创建的文章会自动标记 <code>source='api'</code></p>
|
||
|
||
<h4>请求参数</h4>
|
||
<table class="layui-table" lay-skin="line">
|
||
<thead>
|
||
<tr><th>参数</th><th>类型</th><th>必填</th><th>说明</th></tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr><td>title</td><td>string</td><td>是</td><td>文章标题</td></tr>
|
||
<tr><td>content</td><td>string</td><td>否</td><td>文章内容（Markdown）</td></tr>
|
||
<tr><td>content_html</td><td>string</td><td>否</td><td>文章内容（HTML）</td></tr>
|
||
<tr><td>desc</td><td>string</td><td>否</td><td>文章摘要</td></tr>
|
||
<tr><td>poster</td><td>string</td><td>否</td><td>封面图 URL</td></tr>
|
||
<tr><td>type</td><td>string</td><td>否</td><td>文章类型，默认 "1"</td></tr>
|
||
<tr><td>status</td><td>int</td><td>否</td><td>状态，默认 0（草稿）</td></tr>
|
||
<tr><td>content_type</td><td>string</td><td>否</td><td>内容类型: "html"(默认) 或 "markdown"<br/>当为 "markdown" 时，系统会自动将 content 转换为 HTML 存储到 content_html 字段</td></tr>
|
||
<tr><td>categorys</td><td>array</td><td>否</td><td>分类 ID 数组，如 [1, 2]</td></tr>
|
||
<tr><td>tags</td><td>array</td><td>否</td><td>标签 ID 数组，如 [1, 2]</td></tr>
|
||
<tr><td>publish_time</td><td>string</td><td>否</td><td>发布时间，格式为 Y-m-d H:i:s，如 2024-01-15 14:30:00；当 status=1 且未传或传空字符串时，系统自动使用当前时间</td></tr>
|
||
</tbody>
|
||
</table>
|
||
<p style="color:#888;margin-top:8px;"><strong>注：</strong><code>create_time</code> 和 <code>update_time</code> 由系统自动生成，客户端无需设置也无法修改。</p>
|
||
|
||
<h4>请求示例（HTML）</h4>
|
||
<div class="api-code">curl -X POST \
|
||
"https://example.com/index.php/api/articles/save" \
|
||
-H "Authorization: Bearer your_api_key" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"title": "新文章标题",
|
||
"content": "文章内容",
|
||
"status": 1,
|
||
"publish_time": "2024-01-15 14:30:00",
|
||
"categorys": [1, 2],
|
||
"tags": [3]
|
||
}'</div>
|
||
|
||
<h4>请求示例（Markdown）</h4>
|
||
<div class="api-code">curl -X POST \
|
||
"https://example.com/index.php/api/articles/save" \
|
||
-H "Authorization: Bearer your_api_key" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"title": "Markdown 文章",
|
||
"content": "# 标题\n\n段落内容",
|
||
"content_type": "markdown",
|
||
"type": "1",
|
||
"status": 1,
|
||
"categorys": [1, 2],
|
||
"tags": [3]
|
||
}'</div>
|
||
|
||
<h4>返回示例</h4>
|
||
<div class="api-code">{
|
||
"code": 0,
|
||
"msg": "创建成功",
|
||
"data": {
|
||
"id": 42,
|
||
"uid": "6501a2b3c4d5e"
|
||
}
|
||
}</div>
|
||
</div>
|
||
|
||
<h3>POST /api/articles/update - 编辑文章 <span class="permission-tag" style="background:#FF5722;">需对应写入权限</span></h3>
|
||
<div class="api-section">
|
||
<p>Content-Type: <code>application/json</code></p>
|
||
<p>权限规则：</p>
|
||
<ul style="padding-left:20px; margin:4px 0;">
|
||
<li><code>source='api'</code> 的文章：需要 <code>can_write_own=1</code></li>
|
||
<li><code>source='admin'</code> 的文章：需要 <code>can_write_other=1</code></li>
|
||
</ul>
|
||
|
||
<h4>请求参数</h4>
|
||
<table class="layui-table" lay-skin="line">
|
||
<thead>
|
||
<tr><th>参数</th><th>类型</th><th>必填</th><th>说明</th></tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr><td>id</td><td>int</td><td>是</td><td>文章 ID</td></tr>
|
||
<tr><td>title</td><td>string</td><td>否</td><td>文章标题</td></tr>
|
||
<tr><td>content</td><td>string</td><td>否</td><td>文章内容（Markdown）</td></tr>
|
||
<tr><td>content_html</td><td>string</td><td>否</td><td>文章内容（HTML）</td></tr>
|
||
<tr><td>desc</td><td>string</td><td>否</td><td>文章摘要</td></tr>
|
||
<tr><td>poster</td><td>string</td><td>否</td><td>封面图 URL</td></tr>
|
||
<tr><td>status</td><td>int</td><td>否</td><td>状态</td></tr>
|
||
<tr><td>content_type</td><td>string</td><td>否</td><td>内容类型: "html"(默认) 或 "markdown"<br/>当为 "markdown" 时，系统会自动将 content 转换为 HTML 存储到 content_html 字段</td></tr>
|
||
<tr><td>categorys</td><td>array</td><td>否</td><td>分类 ID 数组（全量覆盖）</td></tr>
|
||
<tr><td>tags</td><td>array</td><td>否</td><td>标签 ID 数组（全量覆盖）</td></tr>
|
||
<tr><td>publish_time</td><td>string</td><td>否</td><td>发布时间，格式为 Y-m-d H:i:s，如 2024-01-15 14:30:00</td></tr>
|
||
</tbody>
|
||
</table>
|
||
<p style="color:#888;margin-top:8px;"><strong>注：</strong><code>create_time</code> 和 <code>update_time</code> 由系统自动生成，客户端无需设置也无法修改。</p>
|
||
|
||
<h4>请求示例</h4>
|
||
<div class="api-code">curl -X POST \
|
||
"https://example.com/index.php/api/articles/update" \
|
||
-H "Authorization: Bearer your_api_key" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"id": 42,
|
||
"title": "修改后的标题",
|
||
"status": 1
|
||
}'</div>
|
||
|
||
<h4>返回示例</h4>
|
||
<div class="api-code">{
|
||
"code": 0,
|
||
"msg": "更新成功",
|
||
"data": []
|
||
}</div>
|
||
</div>
|
||
|
||
<h3>POST /api/articles/delete - 删除文章 <span class="permission-tag" style="background:#FF5722;">需对应删除权限</span></h3>
|
||
<div class="api-section">
|
||
<p>权限规则：</p>
|
||
<ul style="padding-left:20px; margin:4px 0;">
|
||
<li><code>source='api'</code> 的文章：需要 <code>can_delete >= 1</code></li>
|
||
<li><code>source='admin'</code> 的文章：需要 <code>can_delete = 2</code></li>
|
||
</ul>
|
||
|
||
<h4>请求参数</h4>
|
||
<table class="layui-table" lay-skin="line">
|
||
<thead>
|
||
<tr><th>参数</th><th>类型</th><th>必填</th><th>说明</th></tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr><td>id</td><td>int</td><td>是</td><td>文章 ID</td></tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<h4>请求示例</h4>
|
||
<div class="api-code">curl -X POST \
|
||
"https://example.com/index.php/api/articles/delete" \
|
||
-H "Authorization: Bearer your_api_key" \
|
||
-d "id=42"</div>
|
||
|
||
<h4>返回示例</h4>
|
||
<div class="api-code">{
|
||
"code": 0,
|
||
"msg": "删除成功",
|
||
"data": []
|
||
}</div>
|
||
</div>
|
||
|
||
<h2>4. 附件接口</h2>
|
||
|
||
<h3>GET /api/attachments/index - 附件列表 <span class="permission-tag">所有有效 Key</span></h3>
|
||
<div class="api-section">
|
||
<h4>请求参数</h4>
|
||
<table class="layui-table" lay-skin="line">
|
||
<thead>
|
||
<tr><th>参数</th><th>类型</th><th>必填</th><th>说明</th></tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr><td>page</td><td>int</td><td>否</td><td>页码，默认 1</td></tr>
|
||
<tr><td>limit</td><td>int</td><td>否</td><td>每页数量，默认 20</td></tr>
|
||
<tr><td>type</td><td>string</td><td>否</td><td>附件类型</td></tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<h4>请求示例</h4>
|
||
<div class="api-code">curl -X GET \
|
||
"https://example.com/index.php/api/attachments/index?page=1&limit=10" \
|
||
-H "Authorization: Bearer your_api_key"</div>
|
||
|
||
<h4>返回示例</h4>
|
||
<div class="api-code">{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 1,
|
||
"name": "image.png",
|
||
"save_name": "20260401_abc.png",
|
||
"url": "/uploads/20260401_abc.png",
|
||
"type": "image",
|
||
"size": 102400,
|
||
"source": "api",
|
||
"create_time": 1700000000
|
||
}
|
||
],
|
||
"total": 50,
|
||
"page": 1
|
||
}
|
||
}</div>
|
||
</div>
|
||
|
||
<h3>POST /api/attachments/upload - 上传附件 <span class="permission-tag" style="background:#FF5722;">can_write_own=1</span></h3>
|
||
<div class="api-section">
|
||
<p>Content-Type: <code>multipart/form-data</code></p>
|
||
<p>上传的附件会自动标记 <code>source='api'</code></p>
|
||
|
||
<h4>请求参数</h4>
|
||
<table class="layui-table" lay-skin="line">
|
||
<thead>
|
||
<tr><th>参数</th><th>类型</th><th>必填</th><th>说明</th></tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr><td>file</td><td>file</td><td>是</td><td>上传的文件</td></tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<h4>请求示例</h4>
|
||
<div class="api-code">curl -X POST \
|
||
"https://example.com/index.php/api/attachments/upload" \
|
||
-H "Authorization: Bearer your_api_key" \
|
||
-F "file=@/path/to/image.png"</div>
|
||
|
||
<h4>返回示例</h4>
|
||
<div class="api-code">{
|
||
"code": 0,
|
||
"msg": "上传成功",
|
||
"data": {
|
||
"id": 10,
|
||
"name": "image.png",
|
||
"url": "/uploads/20260401_abc.png",
|
||
"size": 102400
|
||
}
|
||
}</div>
|
||
</div>
|
||
|
||
<h3>POST /api/attachments/delete - 删除附件 <span class="permission-tag" style="background:#FF5722;">需对应删除权限</span></h3>
|
||
<div class="api-section">
|
||
<p>权限规则：</p>
|
||
<ul style="padding-left:20px; margin:4px 0;">
|
||
<li><code>source='api'</code> 的附件：需要 <code>can_delete >= 1</code></li>
|
||
<li><code>source='admin'</code> 的附件：需要 <code>can_delete = 2</code></li>
|
||
</ul>
|
||
|
||
<h4>请求参数</h4>
|
||
<table class="layui-table" lay-skin="line">
|
||
<thead>
|
||
<tr><th>参数</th><th>类型</th><th>必填</th><th>说明</th></tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr><td>id</td><td>int</td><td>是</td><td>附件 ID</td></tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<h4>请求示例</h4>
|
||
<div class="api-code">curl -X POST \
|
||
"https://example.com/index.php/api/attachments/delete" \
|
||
-H "Authorization: Bearer your_api_key" \
|
||
-d "id=10"</div>
|
||
|
||
<h4>返回示例</h4>
|
||
<div class="api-code">{
|
||
"code": 0,
|
||
"msg": "删除成功",
|
||
"data": []
|
||
}</div>
|
||
</div>
|
||
|
||
<h2>5. 权限查询接口</h2>
|
||
|
||
<h3>GET /api/api_key_info/info - 查询当前 Key 权限 <span class="permission-tag">所有有效 Key</span></h3>
|
||
<div class="api-section">
|
||
<p>查询当前 API Key 的权限信息，无需额外参数。</p>
|
||
|
||
<h4>请求示例</h4>
|
||
<div class="api-code">curl -X GET \
|
||
"https://example.com/index.php/api/api_key_info/info" \
|
||
-H "Authorization: Bearer your_api_key"</div>
|
||
|
||
<h4>返回示例</h4>
|
||
<div class="api-code">{
|
||
"code": 0,
|
||
"msg": "success",
|
||
"data": {
|
||
"admin_id": 1,
|
||
"can_write_own": 1,
|
||
"can_write_other": 0,
|
||
"can_delete": 1,
|
||
"permissions_text": {
|
||
"can_write_own": "可管理自己的数据",
|
||
"can_write_other": "不可管理后台数据",
|
||
"can_delete": "仅删除API数据"
|
||
}
|
||
}
|
||
}</div>
|
||
</div>
|
||
|
||
<h2>6. 错误码</h2>
|
||
<table class="layui-table" lay-skin="line">
|
||
<thead>
|
||
<tr><th>错误码</th><th>说明</th></tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr><td>0</td><td>成功</td></tr>
|
||
<tr><td>401</td><td>认证失败（无效或已禁用的 API Key）</td></tr>
|
||
<tr><td>403</td><td>权限不足</td></tr>
|
||
<tr><td>500</td><td>业务错误（参数缺失、资源不存在等）</td></tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
{include file='common/_right'/}
|
||
</div>
|
||
</div>
|
||
</body>
|
||
|
||
</html>
|