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

点击查看apidoc生成文档demo

1 环境和工具

  • win10

  • apidoc：注释生成api文档

  • wkhtmltopdf：apidoc生成的是html，不适合传播，于是通过wkhtmltopdf将html转换成pdf文件

  • git：命令行工具和代码版本控制工具（非必要）

  • Typora：markdown文件编辑工具（非必要）

  • 文本编辑工具：VSCode（非必要）

2 准备

（1）apidoc的安装

  • 安装Nodejs

    $ 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的安装

$ 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 安利

posted @ 2018-09-21 11:44  月下小魔王  阅读(1982)  评论(0)  编辑  收藏  举报