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