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