开放API
<p><strong>介绍</strong></p>
<p>showdoc开放文档编辑的API，供使用者更加方便地操作文档数据。利用开放API，你可以自动化地完成很多事。例如下面列举三个典型的应用场景：</p>
<ul>
<li>
<p>假如你的团队有很多现成的文档资料，但这些文档资料大多以word的形式存在。如果人工复制粘粘，工作量会有点多。此时你可以写一个自动脚本，从文件中生成文档，然后通过showdoc的开放api批量地把文档更新进去。</p>
</li>
<li>
<p>你是个后端程序员，你想在写完代码后，文档能自动更新到showdoc。为了实现这个效果，你可以写一个脚本程序，根据你项目代码的结构，自动生成文档数据，然后通过showdoc的开放api自动更新。</p>
</li>
<li>你有很多笔记教程，存在笔记软件或者网站博客中，但你想把它们归类在一起供人们查阅。 这时你可以写程序批量导入showdoc</li>
</ul>
<p>开放API提供的是一种自动更新的能力，使用场景不止上面所说的。更多场景请发挥你的想象力吧！</p>
<p>出于数据安全考虑，showdoc提供的API只能用于添加/编辑文档，无法删除文档。如果要使用更高级的操作，请登录showdoc网页完成。下面是API文档的技术细节，仔细阅读参数说明有助于你理解怎么使用API。阅读明白后可用在线API测试工具进行测试：<a href="http://runapi.showdoc.cc/">http://runapi.showdoc.cc/</a></p>
<p><strong>请求URL：</strong> </p>
<ul>
<li>
<p>如果你使用www.showdoc.com.cn ,则请求URL为</p>
<p><code>https://www.showdoc.cc/server/api/item/updateByApi</code></p>
</li>
<li>
<p>如果你使用私有版的showdoc ,则请求url为</p>
<p><code>http://xx.com/server/index.php?s=/api/item/updateByApi</code></p>
</li>
</ul>
<p><strong>请求方式：</strong></p>
<ul>
<li>POST </li>
</ul>
<p><strong>参数：</strong> </p>
<table>
<thead>
<tr>
<th style="text-align: left;">参数名</th>
<th style="text-align: left;">必选</th>
<th style="text-align: left;">类型</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">api_key</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">string</td>
<td>api_key，认证凭证。登录showdoc，进入具体项目后，点击项目设置-"开放API"便可看到</td>
</tr>
<tr>
<td style="text-align: left;">api_token</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">string</td>
<td>同上</td>
</tr>
<tr>
<td style="text-align: left;">cat_name</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">string</td>
<td>可选参数。当页面文档处于目录下时，请传递目录名。当目录名不存在时，showdoc会自动创建此目录。需要创建多层目录的时候请用斜杆隔开，例如 "一层/二层/三层"</td>
</tr>
<tr>
<td style="text-align: left;">page_title</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">string</td>
<td>页面标题。请保证其唯一。（或者，当页面处于目录下时，请保证页面标题在该目录下唯一）。当页面标题不存在时，showdoc将会创建此页面。当页面标题存在时，将用page_content更新其内容</td>
</tr>
<tr>
<td style="text-align: left;">page_content</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">string</td>
<td>页面内容，可传递markdown格式的文本或者html源码</td>
</tr>
<tr>
<td style="text-align: left;">s_number</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">number</td>
<td>可选，页面序号。默认是99。数字越小，该页面越靠前</td>
</tr>
</tbody>
</table>
<p><strong>成功时的返回示例</strong></p>
<pre><code> {
"error_code" : "0",
"data" : {
"page_id" : "101921",
"author_uid" : "0",
"author_username" : "from_api",
"item_id" : "12011",
"cat_id" : "25619",
"page_title" : "api测试",
"page_comments" : "",
"page_content" : "我是测试内容555455666666666",
"s_number" : "99",
"addtime" : "1484444430"
}
}
</code></pre>
<p><strong>认证失败时的返回示例</strong></p>
<pre><code> {
"error_code" : "10306",
"error_message" : "api_key 或 api_token 不匹配"
}
</code></pre>