Files
ulthon_information/view/index/api_doc/index.html
augushong bcd00e32ea refactor(phone-image): Wave 2 - form, controller, JS engine, API updates
T3: Add cover_text textarea to post edit form

T4: Update Post controller - content copy + cover_text passing

T5: Refactor JS engine - remove old APIs, add forced breaks, page numbers, per-page alignment

T8: Add cover_text to API default_fields, apidoc (4 places), AGENTS.md
2026-05-02 09:16:05 +08:00

567 lines
25 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!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",
"cover_text": "",
"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": "&lt;p&gt;HTML内容&lt;/p&gt;",
"content_type": "html",
"desc": "摘要",
"cover_text": "封面文案内容示例",
"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>cover_text</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>cover_text</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 &gt;= 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 &gt;= 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>