API 接口
本文档介绍 mdView 文档系统提供的 API 接口。
接口概述
文档搜索接口
搜索文档
请求：
GET /search?q=关键词
参数：
响应：
{
"results": [
{
"id": 1,
"name": "简介",
"path": "intro.md",
"url_path": "intro",
"breadcrumb": "",
"snippet": "{{{mdView}}} 是一个轻量级 PHP 文档管理系统..."
}
],
"total": 1
}
文档管理接口
获取文档树
请求：
GET /admin/api/documents
响应：
{
"data": [
{
"id": 1,
"parent_id": 0,
"name": "简介",
"path": "intro.md",
"type": "file",
"sort_order": 1,
"children": []
}
]
}
同步文档（文件系统 → 数据库）
请求：
POST /admin/api/sync-docs
响应：
{
"success": true,
"stats": {"added": 2, "updated": 3, "deleted": 0}
}
认证接口
管理员登录
请求：
POST /admin/api/login
Content-Type: application/json
{
"username": "admin",
"password": "admin123"
}
响应：
{
"success": true
}
登录成功后，服务器会设置 session cookie，后续管理接口需携带此 cookie。
用户管理接口
获取用户列表
请求：
GET /admin/api/users
响应：
{
"success": true,
"data": [
{
"id": 1,
"username": "admin",
"role": "super_admin",
"role_id": 1,
"role_slug": "super_admin",
"role_name": "超级管理员",
"created_at": "2026-01-01 10:00:00"
}
]
}
创建用户
请求：
POST /admin/api/users
Content-Type: application/json
{
"username": "newuser",
"password": "password123",
"role_id": 2
}
响应：
{
"success": true,
"id": 4
}
更新用户
请求：
PUT /admin/api/users
Content-Type: application/json
{
"id": 4,
"role_id": 3
}
响应：
{
"success": true
}
删除用户
请求：
DELETE /admin/api/users
Content-Type: application/json
{
"id": 4
}
响应：
{
"success": true
}
角色管理接口
获取角色列表
请求：
GET /admin/api/roles
响应：
{
"success": true,
"data": [
{
"id": 1,
"name": "超级管理员",
"slug": "super_admin",
"description": "拥有所有权限",
"permissions": ["*"],
"level": 100
}
]
}
创建角色
请求：
POST /admin/api/roles
Content-Type: application/json
{
"name": "新角色",
"slug": "new_role",
"description": "自定义角色",
"permissions": ["documents.view", "documents.create"],
"level": 0
}
静态化构建接口
触发静态构建
请求：
POST /admin/api/static-build
Content-Type: application/json
{
"base_url": "https://docs.example.com",
"output_dir": "/var/www/static"
}
参数：
响应：
{
"success": true,
"stats": {
"pages": 21,
"errors": [],
"elapsed": 0.04,
"timestamp": "2026-05-20 16:15:51"
}
}
错误响应
所有接口出错时返回统一格式：
{
"success": false,
"error": "错误描述信息"
}
或（未登录时）：
{
"error": "Unauthorized"
}
HTTP 状态码：