apidoc 生成接口文档 | Suremotoo's Blog

快速生成接口文档HTML格式、MARKDOWN格式

生成HTML格式

一、安装apidoc

安装前，请确保本机已安装node

npm install apidoc -g

二、安装后创建APIDOC 结构

可以参考我的文件夹目录：

──doc                   文件夹
├── apidoc.json         配置文件
├── gen                 生成api文档的目录
├── rules               生成文档参数文件夹
│   └── Demo.java       具体api
├── footer.md           页脚配置（可选）
├── header.md           头部配置（可选）
└── template            模板（可选）

先创建个文件夹命名为: doc (名字随意) ，紧接着在文件夹中创建 apidoc.json 文件，apidoc.json 的内容可参考如下（实际使用中, 删除注释）:

apidoc.json

{
  "name": "apidoc-example",
  "version": "0.3.0",
  "description": "apiDoc example project",
  "title": "Custom apiDoc browser title",
  "url": "https: {URL}/",
  "header": {
    "title": "",//自定义头部标题
    "filename": "header.md" // header文件
  },
  "footer": {
    "title": "", //自定义页脚标题
    "filename": "footer.md" // footer文件
  },
  "template": {
    "withGenerator": false, // 是否展示apidoc版权生成信息
    "withCompare": false // 是否开启版本对比
  }
}

实际上，最简单的apidoc.json 文件可以只写: name、version、description就可以了，其他的都是可选配置，如下：

apidoc.json（精简版）

{
  "name": "example",
  "version": "0.1.0",
  "description": "A basic apiDoc example"
}

在 doc 文件夹下，创建 rules 文件夹，再在 rules 文件夹下创建 Demo.java 文件夹，demo.java 内容使用样例：

Demo.java

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */
public void getUser(String firstname, String lastname);

三、生成文档

执行生成命令

apidoc -i rules/ -o gen/

命令的意思就是：将 rules 文件夹下的所有配置好的文件生成网页形式的文档, 并将文件生成到 gen 文件夹下

Bingo～

生成markdown形式

一、安装apidoc-markdown

安装前，请确保本机已安装node

npm install apidoc-markdown -g

二、生成文档

执行生成命令

apidoc-markdown -p gen -o gen/doc_markdown.md

命令的意思就是：将 gen 文件夹下生成好的网页形式的文档, 转换成 doc_markdown.md 文件

⚠️⚠️注意：要使用apidoc-markdown，先用apidoc生成网页形式文档，再进行markdown文件的生成

apidoc 命令参数表

参数	描述
-f --file-filters	指定读取文件的文件名过滤正则表达式(可指定多个) 例如: `apidoc -f ".\\.js$" -f ".\\.ts$"` 意为只读取后缀名为js和ts的文件默认值:`.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	指定不读取的文件名过滤正则表达式(可指定多个) 例如:`apidoc -e ".*\\.js$"` 意为不读取后缀名为js的文件默认:`''`
-i, --input	指定读取源文件的目录例如：`apidoc -i myapp/` 意为读取`myapp/`目录下面的源文件默认值:`./`
-o, --output	指定输出文档的目录例如：`apidoc -o doc/` 意为输出文档到`doc`目录下默认值:`./doc/`
-t, --template	指定输出的模板文件例如:`apidoc -t mytemplate/` 默认:`path.join(__dirname, '../template/')(使用默认模板)`
-c, --config	指定包含配置文件(apidoc.json)的目录例如:`apidoc -c config/` 默认:`./`
-p, --private	输出的文档中是否包含私有api 例如:`apidoc -p true` 默认:`false`
-v, --verbose	是否输出详细的debug信息例如:`apidoc -v true` 默认:`false`
-h, --help	查看帮助文档

apidoc-markdown 命令参数表

参数	描述
-p, --path	指定apidoc生成的文档目录
-o, --output	指定输出的markdown文件路径(包含文件名) 例如:`apidoc-markdown -o output_dir/markdown_name.md`
-t, --template	指定生成markdown文件的模板文件(EJS模板文件) 默认:`使用工具自带的模板文件`

本文由 Suremotoo 创作，采用知识共享署名4.0 国际许可协议进行许可
本站文章除注明转载/出处外，均为本站原创或翻译，转载前请务必署名
最后编辑时间为: Feb 22,2020