在自定生成api文档方面以前都是使用swagger.json结合swagger工具来生成文档,偶然发现了apidoc这个生成api的工具,发现使用起来比swagger更加简单,下面整理一下使用过程:
1、安装
首先通过npm全局安装apidoc
$ npm install apidoc -g
2、使用
使用的时候最主要是参考官方文档 ,apidoc文档,文档中清晰的记录了怎么使用的过程,最好也要看一下apidoc的github地址,从哪里你可以看到一个简单的example,
下面就是利用github上apidoc的example来作为实例,example的结构如下:
weifandeMacBook-Pro:example weifan$ ls _apidoc.js apidoc.json example.js footer.md header.md
3、生成api文档
首先我们在执行apidoc命令的目录下,新建一个apiDocs文件,命令如下:
mkdir apiDocs
然后执行生成api文档命令,如下:
$ apidoc -i example/ -o apiDocs/
其中apidoc 参数如下:
-
- -i
读取用于生成文档的目录,比如src目录 - -o
生成api文档静态页面的目录 - -t
自定义的模板目录,默认使用apiDoc的模板 - -f “.*\.java$”
解析符合正则表达式的文件 - -h
显示帮助信息
- -i
在你运行上面命令的时候如果example文件夹下没有apidoc.json这个文件,则会出现一下警告信息:
warn: Please create an apidoc.json configuration file. info: Done.
说明你没有配置生成api的配置文件(如果没有其实也是可以生成的只不过是默认格式)。
此时你会看到apiDocs文件夹下回有生成的index.html文件,在浏览器中运行这个文件,你就会看到你生成的api文档了。
5、配置 apidoc.json
在执行 apidoc
命令的目录执行创建apidoc.json文件,并加入以下内容:
{ "name": "apidoc-example", "version": "0.3.0", "description": "apidoc example project", "title": "Custom apiDoc browser title", "url" : "https://api.github.com/v1", "sampleUrl": "https://api.github.com/v1", "header": { "title": "My own header title", "filename": "header.md" }, "footer": { "title": "My own footer title", "filename": "footer.md" }, "template": { "withCompare": true, "withGenerator": true } }
-
- name
文档内容的最大标题 - version
文档的版本号,一般保持在最新 - description
文档的描述 - title
显示网页的title - url
每个api地址前缀 - sampleUrl
请求示例工具的地址前缀,当有此项时,会出现该工具 - header/footer
文档的头部和尾部- title
头/尾部标题 - filename
头部markdown文件
- title
- template
- withCompare
自动生成版本比较功能的文件,默认true
- withGenerator
生成默认的apidoc版权,默认true
- withCompare
- name
6、apiDoc 注解
下面是apidoc的注解,最主要还是要参照官方文档。
- @api {method} path [title]
method
请求方式: get/post/put…path
User/registertitle
标题 - @apiDescription text
api描述 - @apiError [(group)] [{type}] field [description]
- @apiErrorExample [{type}] [title]
example - @apiExample [{type}] title
example - @apiGroup name
- @apiHeader [(group)] [{type}] [field=defaultValue] [description]
- @apiHeaderExample [{type}] [title]
example - @apiIgnore [hint]
- @apiName name
- @apiParam [(group)] [{type}] [field=defaultValue] [description]
- @apiParamExample [{type}] [title]
example - @apiPermission name
- @apiSampleRequest url
- @apiSuccess [(group)] [{type}] field [description]
- @apiSuccessExample [{type}] [title]
example - @apiUse name
- @apiVersion version
问题
- 无法生成带有历史版本比较功能
必须同时加上@apiVersion
@apiName
@apiGroup
这个三个注解 - @apiName后面不要使用中文介绍,必须要使用英文,不然这个api可能会被隐藏。详见:https://github.com/apidoc/apidoc/issues/431
- 最好不要包含一些特殊字符,特殊字符可能会导致编译有问题
参考
官方文档: http://apidocjs.com
官方示例: https://github.com/apidoc/apidoc/tree/master/example