编写API文档

创建于 2023-03-20 / 最近更新于 2023-03-21 / 777
字体: [默认] [大] [更大]

功能介绍

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

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

image.png

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

请求方法和地址栏

请求方法

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

image.png

地址栏和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参数栏目中显示出来。如下图所:

image.png

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

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.gif
(上图黄底色的框则为当前API返回的结果)

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

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

image.png

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

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

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

image.png

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

apicomplete.gif


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

修改API格式模板

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

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

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

参数 说明
$api_url API请求地址
$api_method API请求方法
$data API参数说明的数组:GET参数、Header参数、Body参数
$response API响应结果数组:成功和失败
10577 人点赞过