Api文档自动生成之apiDoc简介

发表于   |   分类于

简介

apiDoc 是一个基于nodejs自动生成RESTful Api文档的工具，提供了api版本差异比较、自定义末班等功能。

去年和朋友开发一个app，我包下了Android和后端，当时为了让他更好的看懂api和便于后期的维护，专门写了一个api的PHP程序，发现这个api程序还欠缺很多东西加上没有太多时间就不再维护了。后来发现了apiDoc这个库，一直放着没有时间来仔细看，刚好这两天有时间，把这个库学习完了。

安装

安装 npm 的前提下

1
$ npm install apidoc -g

使用

1
2
3
4
5
6
7
8
9
10
11
## 目录结构

|- apidoc/
  |- apidoc.json
  |- header.md
  |- footer.md
  |- src/
    |- _apidoc.java
    |- User.java
  |- doc/
  |- template/

生成api文档

1
$ apidoc -i src/ -o doc/

apidoc 参数

  • -i
    读取用于生成文档的目录，比如src目录
  • -o
    生成api文档静态页面的目录
  • -t
    自定义的模板目录，默认使用apiDoc的模板
  • -f “.*\.java$”
    解析符合正则表达式的文件
  • -h
    显示帮助信息

配置 apidoc.json

在执行 apidoc 命令的目录(apidoc/)创建apidoc.json文件，并加入以下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "name": "FingerArt API Document",
  "version": "0.2.0",
  "description": "A sample of User API document generated from apiDoc",
  "title": "FingerArt API",
  "url" : "",
  "sampleUrl": "http://fingerart.me:44",
  "header": {
    "title": "Overview",
    "filename": "header.md"
  },
  "footer": {
    "title": "Copyright",
    "filename": "footer.md"
  },
  "template": {
    "withGenerator": false
  }
}
  • name
    文档内容的最大标题
  • version
    文档的版本号，一般保持在最新
  • description
    文档的描述
  • title
    显示网页的title
  • url
    每个api地址前缀
  • sampleUrl
    请求示例工具的地址前缀，当有此项时，会出现该工具
  • header/footer
    文档的头部和尾部
    • title
      头/尾部标题
    • filename
      头部markdown文件
  • template
    • withCompare
      自动生成版本比较功能的文件，默认 true
    • withGenerator
      生成默认的apidoc版权，默认 true

apiDoc 注解

  • @api {method} path [title]
    method 请求方式: get/post/put…
    path User/register
    title 标题
  • @apiDescription text
    api描述
  • @apiError [(group)] [{type}] field [description]
  • @apiErrorExample [{type}] [title]
    example
  • @apiExample [{type}] title
    example
  • @apiGroup name
  • @apiHeader [(group)] [{type}] [field=defaultValue] [description]
  • @apiHeaderExample [{type}] [title]
    example
  • @apiIgnore [hint]
  • @apiName name
  • @apiParam [(group)] [{type}] [field=defaultValue] [description]
  • @apiParamExample [{type}] [title]
    example
  • @apiPermission name
  • @apiSampleRequest url
  • @apiSuccess [(group)] [{type}] field [description]
  • @apiSuccessExample [{type}] [title]
    example
  • @apiUse name
  • @apiVersion version

问题

  1. 无法生成带有历史版本比较功能
    必须同时加上 @apiVersion @apiName @apiGroup 这个三个注解

参考

官方文档: http://apidocjs.com
官方示例: https://github.com/apidoc/apidoc/tree/master/example