apidoc的界面比swagger要好看点,我所在的项目一般都是用apidoc作为api接口文档的工具。
安装很简单:
到官网下载nodejs,安装后,执行: npm install apidoc -g,就安装好了apidoc工具。
在你项目的目录下,建一个apidoc.json的文档,加上以下内容即可。具体参数,动手试一下就知道
{
"name": "company sample API",
"version": "0.0.1",
"description": "company sample API 内部接口文档",
"title": "联系人:后台爸爸",
"url": "http://localhost:8091",
"sampleUrl": "http://localhost:8091"
}
最新版的apidoc,新增了可选的参数格式,但是通常我们对外提供的接口,都是json格式提交,但apidoc提供的json格式,是要自己手写的,这样测试起来难免太繁琐,
那我们怎么去掉默认的,直接用form表单提交json格式的数据呢?
很简单:
C:\Users\admin\AppData\Roaming\npm\node_modules\apidoc\template\utils路径下(这个是我自己的路径,各位根据自己的实际路径找哈),找到send_sample_request.js文件,打开后,做如下两步修改:
第一步:
//add url search parameter
if (header['Content-Type'] == 'application/json' ){
url = url + encodeSearchParams(param);
param = bodyJson;
}else if (header['Content-Type'] == 'multipart/form-data'){
url = url + encodeSearchParams(param);
//param = bodyFormData;
param = bodyJson;
}
在120行的位置,将
param = bodyFormData;
修改为:
param = bodyJson;
第二步:
将拼装ajaxRequest的代码段注释掉(128行左右),替换成以下的代码:
var ajaxRequest = {
url: url,
dataType: "json",
contentType: "application/json",
data: JSON.stringify(param),
headers: header,
type: type.toUpperCase(),
success: displaySuccess,
error: displayError
};
OK,以上修改完成后,
表单提交的格式就是json的啦,贴个图说自己没有撒谎:
另外在补充一个:
很多人请求接口是成功的,但是apidoc上不显示结果,(显示什么error0还是啥的忘了),
这个原因是跨域导致的,解决方法很简单,在你的接口上添加一个@CrossOrigin注解就好了。
就是这么干脆。