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