xqf导出为html文件,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 安利