基于注释的接口文档工具apidoc

apidoc是一种基于代码注释自动生成api文档的工具，支持python、java、js、perl等多种语言，使用还是比较简单的。

安装工具包

sudo apt install -y npm
sudo npm install -g apidoc

apidoc配置

apidoc需要一份配置文件来确定生成文档的格式等信息

方式一、apidoc.json

{
  "name": "Control Infinite API文档",
   // 文档名称
  "version": "6.3.0",
  "description": "Control Infinite项目相关API接口文档",
  "title": "QData API",
  "url": "http://127.0.0.1:11100",
  "sampleUrl": "",
  "header": {
    "title": "Overview",
    "filename": "header.md"
  },
  "footer": {
    "title": "Copyright",
    "filename": "footer.md"
  },
  "order": [],   // 根据apiGroup进行排序，没有在列表中的分组自动放到后面
  "template": {
    "forceLanguage": "en",  // 本地化
    "withCompare": true,
  // 是否和旧版本api对比
    "withGenerator": false,
  // 底部是否输出构建信息
    "aloneDisplay": false,  // 当点击某个菜单仅显示此部分内容
  }
}

方式二、package.json

此方式需要将方式一中apidoc.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注释（python代码为例）

class FilterLogHandler(ApiHandler):
    def get(self, key):
        """
        @:keyword select arbiter logs
        @api {get} /longhaul/cluster/arbiterlog(?:<key>) 筛选日志
        @apiVersion 6.3.0
        @apiGroup mxvote
        @apiPermission admin
        @apiDescription 按条件筛选查询仲裁日志
        @apiParam {string="month","halfyear", "year","all"} time 查询的时间范围
        @apiParam {string="stop","start","all"} event 查询的事件
        @apiParam {int} cluster_id 集群id
        @apiParam {int} [count=20]  分页每页的行数
        @apiParam {int} [page=1]  分页的当前页数
        @apiParamExample {json} Request-Example:
        {
            "time": "month",
            "event": "stop",
            "cluster_id": 21,
            "count": 15,
            "page": 2
        }
        @apiSuccess {string} time 日志生成时间
        @apiSuccess {string} notice 事件的详细描述
        @apiSuccessExample {json} Success-Response:
        {
            "data": [
                {
                    "notice": "主机sto19(10.10.90.19)MXVote服务停止。请尽快恢复服务，避免双活集群停止服务",
                    "time": "2017-12-11 11:12:45"
                }
            ],
            "message": "",
            "error_code": 0
        }
        """
        schema_get = Schema({
            "time": UTF8,
            "event": UTF8,
            "cluster_id": Use(int),
            Optional("count"): Use(int),
            Optional("page"): Use(int),
        })
        url_data = self.get_data(schema_get)
        # 获取分页参数
        page, count, offset = self.pagination_params
        url_data["offset"] = offset
        url_data["count"] = count
        data = FilterLog.get_arbiter_log(url_data)
        self.success_response(data)

生成api文档

# 在apidoc.json所在目录执行
# -o 输出位置
# -i 输入
# -t 模板位置（可不指定使用默认）
apidoc -i myapp/ -o apidoc/ -t mytemplate/
# 之后项目下会生成一个apidoc目录，在浏览器打开index.html即可看到效果

版权声明 本文属于本站  原创作品，文章版权归本站及作者所有，请尊重作者的创作成果，转载、引用自觉附上本文永久地址： http://blog.lujianxin.com/x/art/jc533sub1tbe