apidoc接口文档生成工具的使用

apidoc-接口文档生成工具

apidoc可根据编写注释生成接口文档, 支持多种开发语言, 本文以node为例

apidoc更详细内容参考: apidoc

1.安装

  npm install -g apidoc

2.配置apidoc.json文件

  {
    "name": "接口文档名称",
    "version": "接口文档版本",
    "description": "接口文档描述",
    "title": "标题",
    "url" : "接口地址"
  }

3.使用样例

• @api

@api {method} path [title]
接口调用方法, 路径, 名称

@api {get} /apidoc/add 添加文档

• @apiVersion

@apiVersion version
api版本

@apiVersion 1.0.0

• @apiName

@apiName name
api名称

@apiName addApidoc

• @apiGroup

@apiGroup name
api分组

@apiGroup apidoc

• @apiParam

@apiParam [(group)] [{type}] [field=defaultValue] [description]
请求参数

@apiParam {String} date 添加时间
@apiParam {Object} apidoc 添加文档

• @apiSuccess

@apiSuccess [(group)] [{type}] field [description]
接口成功描述

@apiSuccess {Number} code 结果标识
@apiSuccess {String} msg 结果说明
@apiSuccess {Object} data 结果数据

• @apiError

@apiError [(group)] [{type}] field [description]
接口失败描述

• __apiSuccessExample

@apiSuccessExample [{type}] [title] example
接口成功返回样例

@apiSuccessExample Success-Response:{}

• 样例

/**
 * @api {get} /apidoc/add 添加文档
 * @apiVersion 1.0.0
 * @apiName addApidoc
 * @apiGroup apidoc
 * @apiParam {String} date 添加时间
 * @apiParam {Object} apidoc 添加文档
 * @apiSuccess {Number} code 结果标识
 * @apiSuccess {String} msg 结果说明
 * @apiSuccess {Object} data 结果数据
 * @apiSuccessExample Success-Response:
 * {
 *   code: 200,
 *   msg: '新增成功',
 *   data: {
 *     id: '10086',
 *     name: 'apidoc'
 *   }
 * }
 */ 

4.生成接口文档

apidoc -i [读取注释的目录] -o [生成接口文档的目录]

apidoc -i /routes -o apidoc/

找到输出目录下的index.html文件,打开即可查看接口文档