apidoc 生成接口文档

in 代码 with 0 comment

api-icon

快速生成接口文档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模板文件)
默认:使用工具自带的模板文件