DokuWiki 远程 API 概述

DokuWiki 提供了一个强大的远程 API 系统，允许外部应用程序以编程方式与 wiki 交互。这个 API 支持 XML-RPC 和 JSON-RPC 协议，使其可以从各种编程语言和环境中访问。

API 架构

DokuWiki 的远程 API 系统由以下主要组件组成：

入口点：xmlrpc.php 和 jsonrpc.php 文件
协议处理器：XmlRpcServer 和 JsonRpcServer 类
API 核心：Api 和 ApiCore 类
插件系统：通过 RemotePlugin 类扩展 API Api.php:31-36

启用 API

默认情况下，出于安全考虑，远程 API 是禁用的。要启用它，需要在配置中设置：

$conf['remote'] = 1;  
$conf['remoteuser'] = 'user1,user2,@group1'; // 特定用户或组

如果 remoteuser 为空，任何已认证的用户都可以访问 API。如果设置为 !!not set!!（默认值），则完全禁用 API。

API 方法结构

API 方法遵循命名空间命名约定：

核心方法：core.methodName（旧版 API 使用 wiki.methodName 或 dokuwiki.methodName）
插件方法：plugin.pluginName.methodName Api.php:31-36

主要 API 功能

DokuWiki 的远程 API 提供了多种功能，包括：

1. 基本信息获取

// 获取 API 版本  
$result = $remote->call('core.getAPIVersion');  

// 获取 Wiki 版本  
$result = $remote->call('core.getWikiVersion');  

// 获取 Wiki 标题  
$result = $remote->call('core.getWikiTitle');

ApiCore.php:35-40

2. 页面操作

// 获取页面内容  
$result = $remote->call('core.getPage', ['page' => 'wiki:dokuwiki']);  

// 保存页面  
$params = [  
    'page' => 'test:page',  
    'text' => '====Title====\nContent',  
    'summary' => 'API update'  
];  
$result = $remote->call('core.savePage', $params);  

// 追加内容到页面  
$params = [  
    'page' => 'test:page',  
    'text' => '\n新内容'  
];  
$result = $remote->call('core.appendPage', $params);

ApiCore.php:50-61

3. 媒体文件操作

// 列出媒体文件  
$result = $remote->call('core.listMedia', ['namespace' => 'wiki']);  

// 获取媒体文件信息  
$result = $remote->call('core.getMediaInfo', ['media' => 'wiki:logo.png']);  

// 上传媒体文件  
$base64 = base64_encode(file_get_contents('local_image.png'));  
$result = $remote->call('core.saveMedia', ['media' => 'wiki:image.png', 'base64' => $base64]);

ApiCore.php:63-72

4. 用户认证和权限

// 登录  
$result = $remote->call('core.login', ['user' => 'username', 'password' => 'password']);  

// 检查当前用户  
$result = $remote->call('core.whoAmI');  

// 检查 ACL 权限  
$result = $remote->call('core.aclCheck', ['page' => 'wiki:dokuwiki']);

ApiCore.php:42-45

实际使用示例

PHP 客户端示例

以下是使用 PHP 调用 DokuWiki API 的完整示例：

<?php  
// 使用 JSON-RPC 调用 DokuWiki API  

// API 端点  
$url = 'https://your-wiki.com/lib/exe/jsonrpc.php';  

// 准备请求数据  
$data = [  
    'id' => 1,  
    'jsonrpc' => '2.0',  
    'method' => 'core.getPage',  
    'params' => ['page' => 'wiki:dokuwiki']  
];  

// 设置 HTTP 基本认证  
$auth = base64_encode('username:password');  

// 发送请求  
$ch = curl_init($url);  
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);  
curl_setopt($ch, CURLOPT_HTTPHEADER, [  
    'Content-Type: application/json',  
    'Authorization: Basic ' . $auth  
]);  
curl_setopt($ch, CURLOPT_POST, true);  
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));  

// 获取响应  
$response = curl_exec($ch);  
curl_close($ch);  

// 解析响应  
$result = json_decode($response, true);  
print_r($result);

创建自定义远程 API 插件

如果您想扩展 DokuWiki 的 API 功能，可以创建自己的远程插件：

<?php  
/**  
 * 自定义远程 API 插件示例  
 */  
class remote_plugin_example extends \dokuwiki\Extension\RemotePlugin {  
    /**  
     * 获取当前时间  
     */  
    public function getTime() {  
        return date('Y-m-d H:i:s');  
    }  

    /**  
     * 获取特定命名空间的页面数量  
     */  
    public function getPageCount($namespace) {  
        $pages = search($namespace, 'isdir', 'search_allpages');  
        return count($pages);  
    }  
}

RemotePlugin.php:15-25

使用这个插件的 API 调用示例：

// 获取当前时间  
$result = $remote->call('plugin.example.getTime');  

// 获取页面数量  
$result = $remote->call('plugin.example.getPageCount', ['namespace' => 'wiki']);

API 认证和安全

远程 API 请求需要通过以下方式进行认证：

HTTP 基本认证
DokuWiki 会话 cookie（从之前的登录）
JWT 令牌认证（高级）

公共方法可以在启用 API 的情况下无需认证即可访问。API 还可以通过 remotecors 配置选项支持跨域请求。

错误处理

API 调用可能返回错误，每个错误都有特定的错误代码和消息。例如：

{  
  "id": "request-id",  
  "jsonrpc": "2.0",  
  "error": {  
    "code": 121,  
    "message": "The requested page does not exist"  
  }  
}

常见错误代码包括：

121: 请求的页面不存在
132: 拒绝写入空的新 wiki 页面
133: 页面当前被锁定
134: 页面内容被阻止（垃圾内容检查） ApiCore.php:661-687

API 文档

DokuWiki 提供了一个 OpenAPI 文档，可以通过访问 /lib/exe/openapi.php 查看完整的 API 规范。这个文档详细列出了所有可用的 API 方法、参数和返回值。 openapi.php:1-15

Notes

DokuWiki 的远程 API 是一个强大的功能，允许您以编程方式与 wiki 交互。通过 XML-RPC 或 JSON-RPC 协议，您可以执行各种操作，如获取和修改页面内容、上传媒体文件、检查用户权限等。

要使用 API，首先需要在配置中启用它，然后可以通过 HTTP 请求调用各种方法。API 还可以通过创建远程插件进行扩展，以添加自定义功能。

请注意，出于安全考虑，默认情况下 API 是禁用的，使用时应注意权限控制和安全验证。