利用apidoc在注释里写API文档

文章目录

程序员都不喜欢写文档,但是程序员习惯写注释。

所以今天给大家安利一个注释文档的工具——apidoc,一个在注释里边编写API文档的小工具!

安装apidoc

npm install -g apidoc

运行

apidoc -i myapp/ -o apidoc/ -t mytemplate/
  • -i 需要编译的包含注释的文件
  • -o 输入文件夹名称
  • t 模板

具体的详细帮助可以通过apidoc -h查看。

设置(apidoc.json)

我们可以通过apidoc.json文件来设置项目API文档的一些内容。例如:

{ 
  "name": "example", 
  "version": "0.1.0", 
  "description": "apiDoc basic example",
  "title": "Custom apiDoc browser title", 
  "url" : "https://api.github.com/v1"
}

又或者通过package.json来设置apidoc的文档设置也是支持的。

{ 
  "name": "example", 
  "version": "0.1.0", 
  "description": "apiDoc basic example", 
  "apidoc": { 
      "title": "Custom apiDoc browser title", 
      "url" : "https://api.github.com/v1" 
  }
}

注释的编写

@api

@api一般是必须编写的(除非你是用了@apiDefine),不然apidoc编译器会忽略这段注释。

/** 
 * @api {method} path [title]
 */

QQ20170520-131039

@apiGroup

定于api归属的组名,生成的文档会把该api注释归类到该值对应的api组上。

/**
 * @apiGroup name
 */

QQ20170520-131114

@apiName

@apiName用于定义API文档的一个实例,并用作实例名称。

/**
 * @apiName name
 */

QQ20170520-131151

@apiParam

@apiParam用于编写API的参数以及参数的解释。

/**
 * @apiParam [(group)] [{type}] [field=defaultValue] [description]
 */

QQ20170520-131500

@apiParamExample

@apiParamExample参数例子

/**
 * @apiParamExample [{type}] [title]
 *    example
 */

QQ20170520-131623

@apiSuccess

请求成功后的返回字段参数

/**
 * @apiSuccess [(group)] [{type}] field [description]
 */

QQ20170520-131717

@apiSuccessExample

请求成功后返回的字段参数例子

/**
 * @apiSuccessExample [{type}] [title] example
 */

QQ20170520-131809

@apiError & @apiErrorExample

这个的用法跟@apiSuccess、@apiSuccessExample的用法相类似。

举个栗子

下边举一个根据id获取文章资源API的例子

/**
 * @api {get} /articles/:id 根据单个id获取文章信息
 * @apiName 根据id获取文章信息
 * @apiGroup Articles
 *
 * @apiParam (params) {String} id       文章id
 *
 * @apiSuccess {Array} article 返回相应id的文章信息
 *
 * @apiSuccessExample Success-Response:
 *    HTTP/1.1 200 OK
 *      {
 *        "tile": "文章标题2",
 *        "date": 1483941498230,
 *        "author": "classlfz",
 *        "content": "文章的详细内容"
 *       }
 *
 * @apiError (Error 4xx) 404 对应id的文章信息不存在
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 对应id的文章信息不存在
 *     {
 *       "error": err
 *     }
 */

接着我们运行apidoc -i src/ -o docs,就会看到项目里边多了一个docs的文件夹,打开里边的index.html,就可以看到生成的API文档了。如下图:

1626912-5555c6d326baadf2

这样子,我们就可以轻松的通过注释得到一个API文档了,而不需要在写完代码之后还要去打开word或者md文件去另外编写API文档……对于我本人而言,我是比较喜欢这样子的工作方式的。

如果项目是放在github上边的话,我们可以使用github pages来公布API文档,方便协同开发。

写成gulp任务

因为平时用gulp比较多,这里再补上通过gulp任务来生成apidoc文档。

安装依赖

npm install gulp gulp-apidoc --save-dev

编写gulp代码

// 构建apidoc
gulp.task('apidoc', (done) => {
  apidoc({
    src: 'src/',
    dest: 'docs',
    debug: true,
    includeFilters: ['.*\\.js$']
  }, done);
});
原文链接:,转发请注明来源!

发表评论

要发表评论,您必须先登录