點擊查看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文件

4 安利

• apidoc使用參考：http://www.bjhee.com/apidoc.html
• wkhtmltopdf使用參考：https://www.jianshu.com/p/4d65857ffe5e

轉載于:https://www.cnblogs.com/linzhanfly/p/9685794.html

總結

以上是生活随笔為你收集整理的Api文档生成工具与Api文档的传播（pdf）的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。