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 -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