webApi文档好帮手-apidoc使用教程

比眉伴天荒 2022-07-16 15:18 265阅读 0赞

在开发后台接口的过程中，我们肯定要提供一份api接口文档给终端app。

目前大多数的app的接口请求应该都是http+json的方式。 但是一直苦于做不出份漂亮的api文档，用word写，也太丑了。。怎么才能做出一份像腾讯、新浪微博等各种开放api平台那样漂亮的api文档呢？找了好久发现了今天的主角-apidoc。

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

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

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

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

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

支持多种语言：C\#, [ Go][Go], Dart, [ Java][Java], JavaScript, [ PHP][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的源码：

**\[java\]**  [view plain][]   [copy][view plain]

[![在CODE上查看代码片][CODE]][CODE_CODE] [![派生到我的代码片][ico_fork.svg]][ico_fork.svg 1]

1.  /\*\* 
2.   \* 此接口不要去实现，仅作为输出api文档用的 
3.   \* @author xumin 
4.   \* 
5.   \*/  
6.  @Deprecated  
7.  **public** **interface** ApiDoc \{  
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文档。

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

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

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

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

大功告成！

[JavaScript]: http://lib.csdn.net/base/javascript
[laugh.gif]: http://static.blog.csdn.net/xheditor/xheditor_emot/default/laugh.gif
[Link 1]: http://www.shellsec.com/
[Go]: http://lib.csdn.net/base/go
[Java]: http://lib.csdn.net/base/javase
[PHP]: http://lib.csdn.net/base/php
[Python]: http://lib.csdn.net/base/python
[view plain]: http://blog.csdn.net/xumin198908/article/details/41964159#
[CODE]: https://code.csdn.net/assets/CODE_ico.png
[CODE_CODE]: https://code.csdn.net/snippets/553852
[ico_fork.svg]: https://code.csdn.net/assets/ico_fork.svg
[ico_fork.svg 1]: https://code.csdn.net/snippets/553852/fork