apidoc快速生成接口文档

apidoc官方文档
1.@api {method} path [title]

参数名称	描述
method	请求方法
path	请求路径（相对路径）
title	短标题

2.@apiGroup name
表示 API 所属分组名称，它会被解析成一级导航栏菜单标题。注意不能是中文，否则会解析错误

参数名称	描述
name	API分组名称

3.@apiName name
API 接口标识名称。需要注意的是，在同一个 @apiGroup 下，具有相同的 @apiName的 @api 必须通过 @apiVersion 区分，否则后面定义的 @api 会覆盖前面定义的 @api。

参数名称	描述
name	API名称

4.@apiParam [(group)] [{type}] [field=defaultValue] [description]
定义 API 接口需要的请求参数格式

参数名称	描述
选填 (group)	参数分组
选填 {type}	参数类型，包括{Boolean}, {Number}, {String}, {Object}, {String[]}, …
选填 {type{size}})	可以声明参数范围，例如{string{…5}}， {string{2…5}}， {number{100-999}}
选填 {type=allowedValues}	可以声明参数允许的枚举值，例如{string=“small”,“huge”}， {number=1,2,3,99}
field	参数名称
[field]	声明该参数可选
选填 =defaultValue	声明该参数默认值
选填 description	声明该参数描述

5.@apiSuccess [(group)] [{type}] field [description]
定义 API 接口请求成功时返回的数据格式

参数名称	描述
选填 (group)	参数分组，默认为Success 200
选填 {type}	参数类型，包括{Boolean}, {Number}, {String}, {Object}, {String[]}, …
field	参数名称
选填 description	声明该参数描述

6.@apiSuccessExample [{type}] [title] example
API 接口请求成功时返回样例数据。若返回参数结构和含义较为简单，则@apiSuccess和@apiSuccessExample任取其一定义即可

参数名称	描述
选填 {type}	参数类型，包括{Boolean}, {Number}, {String}, {Object}, {String[]}, …
选填 title	返回样例短标题
example	详细返回数据，支持多行

在项目的目录下配置apidoc.json文件

{
  "name": "Autodeploy",  //文档名称
  "version": "0.1.0",  // 版本
  "description": "Autodeploy Api",   // 描述
  "title": "autodeploy",  // 生成的index.html的标题
  "url": "http://www.baidu.com/autodeploy"  // 接口url
}

示例：python中使用apidoc

def opt_item_list_views(request):
    """
    @api {POST} /opt/v1/list_opt_items/ 操作项列表  
    @apiGroup OPT  
    @apiName list_opt_items

    @apiParam {Number} [bizid] 业务id
    @apiParam {Integer=0, 1} [status] 是否关联操作流程 可选
    @apiParam {Object} page 分页
    @apiParam {Integer} page.start 起始页
    @apiParam {Integer} page.limit 条数
    @apiParam {String} [page.sort] 排序字段 可选
    @apiParam {String} [itemname] 搜索字段 以操作项名称搜索

    @apiSuccess {Object} data  数据
    @apiSuccess {Number} data.count  数据总数
    @apiSuccess {Object[]} data.results  操作项列表
    @apiSuccess {Number} data.results.opt_item_id  操作项ID
    @apiSuccess {String} data.results.opt_name  操作项名称
    @apiSuccess {String} data.results.opt_descr  操作项描述
    @apiSuccess {String} data.results.opt_icon_path  操作项图标
    @apiSuccess {String} data.results.creator  创建者
    @apiSuccess {String} data.results.create_time  创建时间
    @apiSuccess {Integer} data.results.file_id  文件id

    @apiSuccessExample {json} Success-Response:
        HTTP/1.1 200 OK
        {
            "code":0,
            "message":"success",
            "data": {
                "count": '',
                "results": [
                    {}
                ]
            }
            "result": true
        }
    """
    message, params = json_to_python(request.body.decode())
    if not params:
        result = False

执行生成文档命令

apidoc -i autodeploy/controller/ -o templates/apidoc/
把autodeploy下的controller下的文件生成接口文档, 并输出到templates下的apidoc文件夹下

-i : 输入某个要生成的文档的文件夹 
-o : 生成的接口文档要放到哪里

在生成的apidoc文件夹里有 index.html双击点开
结果如下: