在写文档是开发者经常要做的事情,今天介绍一个自动生成文档的工具apidoc。使用起来非常简单,一键快速生成文档,操作非常方便。
安装
1 | npm install apidoc -g |
注意安装环境必须要nodejs
配置
在需要写文档的目录编写配置文件apidoc.json
:
1 | { |
上面的例子引入了公共的头部和底部,支持md模式:
footer.md
:
1 | # API 返回值说明 |
header.md
:
1 | ## API 调用规则 |
header和footer是选填的,可以没有!如果需要则apidoc.json
文件进行配置
编辑API
写入一个测试接口src/user.js
1 | /** |
写入一个公共接口模板 src/commonModule.js
上面userApi配置中就应用了该公共模块@apiUse respSuccessModel
1 | /** |
目录结构:
编译
运行生成命令:
1 | apidoc -i src/ -o apidoc/ |
访问
然后在html里面可以直接访问index.html查看文档了
注意:每次更新了接口文件都需要重新执行生成apidoc命令生成。
其他说明
@api
@api {method} path [title]
@api {get} /mission/add 添加任务
HTTP接口调用方法、路径及名称
@apiVersion
@apiVersion version
@apiVersion 1.0.0
api版本
@apiName
@apiName name
@apiName addMission
api 名称
@apiGroup
@apiGroup name
@apiGroup Mission
api 分组
@apiParam
@apiParam [(group)] [{type}] [field=defaultValue] [description]
@apiParam {String} date 添加时间
请求参数
@apiSuccess
@apiSuccess [(group)] [{type}] field [description]
@apiSuccess {Number} code 结果标识
返回数据描述
@apiError
@apiError [(group)] [{type}] field [description]
接口失败描述
@apiSuccessExample
@apiSuccessExample [{type}] [title] example
@apiSuccessExample Success-Response:{}
接口成功返回样例
生成文档
在根目录下执行命令
1 | apidoc -i src/ -o apidoc/ |
读取router文件夹下的注释,输出到apidoc文件夹下
点开apidoc文件夹中index.html会发现已经生成的漂亮的api文档
去掉请求
在编译得到的文件夹中编辑index.html,删除请求相关模块
1 | <script id="template-article-sample-request" type="text/x-handlebars-template"> |
去掉底部版权说明
在编译得到的文件夹中编辑index.html,删除请求相关模
1 | <script id="template-generator" type="text/x-handlebars-template"> |
更多
其他详细教程看官方文档:https://apidocjs.com/