编写API文档

功能介绍

API文档和普通文档并没有太大区别，不要被名字所困惑了。本功能只是将调用API的过程，通过预设的通用模板，根据API工具填写的URL、参数和返回结果渲染出固定的格式内容，从而提升了API文档编写的速度。

在编写API文档时，在选择文档属性为文章时，同时勾选启用API转换文档选项，系统即呼出API调用工具，如下图所示：

本文档可能涉及到一些术语描绘不准确的情况，若有错误还望指出。

请求方法和地址栏

请求方法

在API调试工具中，您可以根据自己API的情况，选择对应的请求方法，如常见的：GET、POST、PUT…… DOC系统基本整合了常见的HTTP请求方法。若您的API接口有自定义的请求类型，您可以通过修改源码来扩充请求方法。

地址栏和GET参数

在浏览器地址栏中看到的URL，或者API文档给出的请求URL地址，只要URL中包含一些参数，一般来说都属于GET参数。如：http://www.pescms.com/?g=API&m=Index&a=index ，该API包含了参数g、m、a。分别对应的值为API、Index、index。

当您在API工具的地址栏中填写上述URL地址，程序会对URL参数进行一个简单的识别。若识别成功，则会在GET参数栏目中显示出来。如下图所：

没有显示出来也没关系，您可以根据自己实际情况，一一填写。

Header设置

有一些API请求需要在header设置指定参数才可以正确响应，您只需要根据API文档要求填写请求的header参数即可。

Body设置

API工具中的Body您只需要理解成是一个POST参数即可，或者理解成浏览器中开发者调试工具中的Payload。

在Body设置中有两个选项：form-data 和 raw

form-data

您只需要理解成传统表单name => value 关系即可，一个表单一个值。

raw

他既可以做到传统表单的name => value 用类似GET参数组装传递给后端，也可以直接发送一个JSON结构体。

• 如我们要POST一个aid为1，name为小明的到后端。在raw可以直接填写： aid=1&name=小明
• 也可以像这样直接发送一个JSON到后端：{“touser”:"1","agentid":1}

执行结果

API执行结果一般来说只有成功和失败。当您完成上面基本参数填写后，点击发送按钮。API工具将会向您填写的API服务器提交对应的信息，并将结果返回。如下图所：

（上图黄底色的框则为当前API返回的结果）

我们根据返回结果，分别依次填写返回成功和返回失败的文本框。

在成功或失败的文本框中输入的为正确的JSON格式，系统在渲染模板时会自动格式化显示。

由于API的返回结果格式是不可控制的，我们无法做过于预测性的分析。因此返回参数说明需要自行填写。

预览请求效果和填写编辑器

只要您每次点击API工具的发送按钮，系统都会在当前浏览器坐标(0,0)的位置弹出API文档渲染结果对话框。如下图所示：

当您认为API预览效果符合要求时，可以在对话框中选择插入到编辑器中。如下图所示：

至此，我们已经完成了API文档编写的过程了！

修改API格式模板

您可能对DOC系统预设的格式模板有修改的要求，您可以参考本小节进行自定定制。

API格式模板文件地址：DOC程序/Public/Theme/Create/Default/Article/Article_api_content_example.php

使用编辑器打开上述文件，模板文件的变量都非常值观清晰，稍微有点PHP基础的您即可轻松进行修改。