Api文档生成工具与Api文档的传播（pdf）

小程序：扫一扫查出行
【扫一扫了解最新限行尾号】
复制小程序

点击查看apidoc生成文档demo

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 -hUsage: 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文件