一般在我们正式的EasyRTC开发过程中,是以pdf或者word的纸质版本作为开发归档文档,html文档不能作为归档文档,所以需要生成pdf文档;有时也会遇到用户需要正式文档情况,这两种情况我们就要将文档生成PDF文档。
apiDoc为一款针对RestfulAPI的文档自动生成工具。在Restful软件架构中,后端人员编写软件开发接口,生成接口文档给前端。apiDoc最终生成的文档为html文件。
后端软件开发接口示例如下:
/**
* @api {POST} /v1/conference/add 01. 添加视频会议
* @apiGroup 02conference
*
* @apiParam {String} name 会议名称
* @apiParam {String} taskID 会议任务号
* @apiParamExample {json} Request-Example
{
"name": "测试视频会议",
"taskID": "task100"
}
*
* @apiSuccess {String} id 会议房间号
* @apiSuccess {String} name 会议名称
* @apiSuccess {Bool} online 会议状态
* @apiSuccess {String} numbers 会议在线人数
* @apiSuccess {String} taskID 会议任务号
* @apiSuccess {String} updateAt 最后更新时间
* @apiSuccessExample {json} Response-Example
{
"code": 200,
"msg":
{
"id": 1331,
"name": "测试视频会议",
"online": false,
"numbers": "0",
"taskID": "task100",
"updateAt": "2020-01-22 00:11:44"
}
}
*/
然后运行一下命令即可生成html文件。
apidoc -i routes -o apidoc
上述命令中-i代表输入文件夹,-o代表输出文件夹,命令总体操作为扫描routes文件夹下的所有文件,然后在apidoc目录下生成html文件。如下所示:
打开index.html文档如下:
以上文档对于阅读非常方便,但是在软件开发流程中,经常有需要生成正式文档的需求,比如word或者pdf文档格式进行保存。
html文档生成pdf文档具体步骤
npm install apidoc-markdown -g
安装完以上工具后即可进行开始制作:
- 运行一下命令将apidoc生成的html文档转换成markdown文件。
apidoc-markdown -p apidoc -o doc_markdown.md
以上命令为扫描apidoc文件夹下的所有文件然后生成doc_markdown.md文档。
- 使用typora打开doc_markdown.md,在文件中选择导出pdf文档即可。
但是直接导出的pdf文档可能有问题,因为导出的markdown文件中会存在html标签,导致生成的文档出现很多
等html标签,非常影响阅读。所以需要对markdown文件进行改造,删除下图示例中的所有html标签。
删除所有标签后,然后再使用typora生成pdf文档即可。最终生成的文档部分截图如下: