1 环境和工具
win10
- apidoc:注释生成api文档
- wkhtmltopdf:apidoc生成的是html,不适合传播,于是通过wkhtmltopdf将html转换成pdf文件
- git:命令行工具和代码版本控制工具(非必要)
- Typora:markdown文件编辑工具(非必要)
文本编辑工具:VSCode(非必要)
2 准备
(1)apidoc的安装
安装Nodejs
- 官网地址:http://nodejs.cn/download/
- 根据自己的系统环境下载并安装
- 检测是否安装成功)
$ node -v v9.9.0 $ npm -v 6.1.0
通过Nodejs的包管理工具安装apidoc
- 安装
$ npm install apidoc -g
- 检测是否安装成功
apidoc -h Usage: C:\Program Files\nodejs\node.exe apidoc [options] Options: -f, --file-filters RegEx-Filter to select files that should be parsed (multiple -f can be used). [.*\.(clj|cls|coffee|cpp|cs|dart|erl|exs?|go|groovy|ino?|java|js|jsx|kt|litcoffee|lua|p|php?|pl|pm|py|rb|scala|ts|vue)$] -e, --exclude-filters RegEx-Filter to select files / dirs that should not be parsed (many -e can be used). [] -i, --input Input / source dirname. [./] -o, --output Output dirname. [./doc/] -t, --template Use template for output files. [C:\Users\Little\AppData\Roaming\npm\node_modules\apidoc\template\] -c, --config Path to directory containing config file (apidoc.json) [./] -p, --private Include private APIs in output. [false] -v, --verbose Verbose debug output. [false] ......
(2)wkhtmltopdf的安装
- 官网下载地址:https://wkhtmltopdf.org/downloads.html
- 根据环境下载并安装
- 检测是否安装成功
$ wkhtmltopdf.exe -V
wkhtmltopdf 0.12.5 (with patched qt)
3 DEMO
(1)apidoc目录结构
- apidoc.json:使用apidoc生成api文档的配置文件
- apidoc.ps1:powershell脚本文件,用于一键生成api文档并打开
- auth.js:api的编写
- general.md:api文档可以包含一个md文件
(2)各个文件的内容
- apidoc.json
{
"name": "Test Api Document",
"version": "0.1.0",
"description": "This Document is Test Api Document.",
"title": "Test Api Document",
"url": "http://api.test.com/v1",
"sampleUrl": "http://api.test.com/v1",
"header": {
"title": "GENERAL",
"filename": "general.md"
},
"template": {
"withCompare": true,
"withGenerator": true
}
}
- apidoc.ps1
Remove-Item -Force -Recurse doc
apidoc -o doc
pause
.\doc\index.html
- auth.js(代码的注释文件)
/**
* @api {post} /auth/token TOKEN
* @apiVersion 0.1.0
* @apiName TOKEN
* @apiGroup Auth
* @apiPermission none
*
* @apiParam {String} username 用户名
* @apiParam {String} password 密码
*
* @apiExample Example usage:
* curl -X POST \
* -H "Content-Type: application/json" \
* -d '{"username":"test","password":"test"}' \
* https://api.test.com/v1/auth/token
*
* @apiDescription 登陆认证并获取token值。
*
* @apiSuccess {Number} status 业务的成功或者失败
* @apiSuccess {String} msg 成功或者失败描述
* @apiSuccess {Object} data 返回的数据
* @apiSuccess {String} data.access_token 下次请求的访问token
* @apiSuccess {Number} data.expires_in token的过期时间
*
* @apiSuccessExample {json} Response:
* HTTP/1.1 200 OK
* {
* "status": 1,
* "msg": "Get Token Success.",
* "data": {
* "access_token": "eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJvcHQiLCJzdWIiOiJhMTE2NDcxNCI
* iIsImlhdCI6MTUxNTY1NjYzMiwiZXhwIjox.aoUcjw2EVc2hDchPgMK4tPou
* PkWuh_jlcpLerO-w1lG_KTNmFmgiKiGAcgAnrYp7xQFpFEBVfwDu7Q",
* "expires_in": 86399
* }
* }
*/
- general.md
## 概述
这个API文档用于测试使用。
(3)生成api文档
- 执行apidoc.ps1脚本
- 或者 apidoc命令
# 目录中多了一个doc目录,打开doc/index.html即可查看api文档
$ apidoc -o doc
(4)html转pdf
$ wkhtmltopdf.exe -s A3 doc/index.html api.pdf
Loading pages (1/6)
Counting pages (2/6)
Resolving links (4/6)
Loading headers and footers (5/6)
Printing pages (6/6)
Done
# 当前目录下多了一个api.pdf文件
4 安利
- apidoc使用参考:http://www.bjhee.com/apidoc.html
- wkhtmltopdf使用参考:https://www.jianshu.com/p/4d65857ffe5e