如何利用apidoc来写接口文档

Posted 2020-09-03

在开发后台接口的过程中，肯定要提供一份api接口文档给终端。一直用word写，太丑了。。怎么才能做出一份漂亮的api文档呢？找了好久发现了今天的主角-apidoc。

官网地址：http://apidocjs.com

开放API已经成为当下主流平台的一个要素，特别对于社交、电商类的平台开放API更成为了竞争力的一种。开放API文档的完整性、可阅读性往往影响着接入方是否能顺利地、快速地接入到平台，一份好的、统一的API文档也是开放平台不可或缺的要素。

apidoc是通过源码中的注释来生成API文档，所以只要识别兼容现今大部分流行语言的注释方法便达到了兼容语言的效果。

有了它，我们只需要在写源码的时候顺手写上一些简单的注释，就可以生成出漂亮的文档了（当然，有同学会问文档不是先定义的吗？你把接口的源码声明好不就ok啦？或者你写点其他的语言也行啊。。  最简单的就是学习下JavaScript，只要学会怎么创建js文件，然后怎么声明function，给function添加注释即可，实在写不了源码，写一个简单的js文件，然后用apidoc生成一下就出文档了）

它可以对API的各种版本等级进行对比。所以无论是前端开发人员还是你都可以追溯API版本的变化。

支持多种语言：C#, Go, Dart, Java, javascript, PHP, TypeScript (all DocStyle capable languages)，CoffeeScript，Erlang，Perl，Python，Ruby。

使用步骤：

1.安装nodejs。去http://www.nodejs.org/下载安装一个nodejs；

2.安装apidoc：命令行输入：npm install apidoc -g    貌似是在线安装的，稍等一下即可。

 

3. 准备一个目录myapp，下面放源码文件，源码文件中要按照apidoc的规范写好注释。具体规范参见官网，我这里就不翻译了。

例如这个java的源码：

 1 /** 
 2  * 此接口不要去实现，仅作为输出api文档用的 
 3  * @author xumin 
 4  * 
 5  */  
 6 @Deprecated  
 7 public interface AipInter {  
 8     /** 
 9      *  
10      * @api {get} /company/list 获取公司信息 
11      * @apiName 获取公司列表 
12      * @apiGroup All 
13      * @apiVersion 0.1.0 
14      * @apiDescription 接口详细描述 
15      *  
16      * @apiParam {int} pageNum分页大小  
17      *  
18      * @apiSuccess {String} code 结果码 
19      * @apiSuccess {String} msg 消息说明 
20      * @apiSuccess {Object} data 分页数据封装 
21      * @apiSuccess {int} data.count 总记录数 
22      * @apiSuccess {Object[]} data.list 分页数据对象数组 
23      * @apiSuccessExample Success-Response: 
24      *  HTTP/1.1 200 OK 
25      * { 
26      * code:0, 
27      * msg:‘success‘, 
28      * data:{} 
29      *  } 
30      *   
31      *  @apiError All 对应<code>id</code>的用户没找到 asdfasdf  
32      *  @apiErrorExample {json} Error-Response: 
33      *  HTTP/1.1 404 Not Found 
34      *  { 
35      *   code:1, 
36      *   msg:‘user not found‘, 
37      *   } 
38      *    
39      * @param param 
40      * @return 
41      * @throws Exception 
42      */  
43     void a();  
44 }  

4. 生成api文档。

进入命令行cd C:\\Users\\ko\\AppData\\Roaming\\npm\\node_modules，这是上面安装的路径部分，在该目录下建个myapp文件夹，把java文件放进去

 

apidoc -i myapp/ -o apidoc/ -t mytemplate/

myapp是当前工作目录下的源码目录

apidoc是用于存放生成出的文档文件的目录

mytemplate是自定义模板文件夹，刚开始用，可以不指定，后面有需要了再研究怎么自定义模板吧。

 

如果看到“success: Done.”说明生成成功 ，到 apidoc目录下打开index.html查看生成的文档.

大功告成！

最后看看一些apidoc常用注解介绍：

apidoc是运用各个不同的注解来完成文档的写作的。学习apidoc，主要就是学习注解的用法。apidoc和命名行的命令很像，由一个注解关键字加一些选项构成。下面介绍一下apidoc主要的注解。

① @api {method} path [title]
这是apidoc必需的注解，用来说明api的方法，访问路径和作用。

② @apiParam [(group)] [{type}] [field=defaultValue] [description]
这个注解用来说明api请求参数的类型，大小和作用。

③ @apiSuccess [(group)] [{type}] field [description]
这个注解说明api返回参数的类型，大小和作用。

更多关于注解的详细用法可以访问官网，上面有详细的用法和示例。