写在之前

apidoc 的优势：
    1. UI 还算可以，
    2. 可以模拟请求
    3. 对原有运行环境无伤害（仅需在开发机器上安装 nodejs 和 apidoc 就可以正常使用，无需对运行环境和项目做结构性修改）
apidoc 的劣势：
    1. 不能本地导出，但是可以通过安装应用包，先导出md文件，然后再转存各种文档格式
    2. 注释代码量有点大；几乎所有的文档信息都要通过注释来提现
    
其他工具存在的问题    
    1. 需要修改代码结构，2. 对py2.7 支持不友好 如Flask-Docs， 3.配置和使用有定复杂

安装nodejs

npm install apidoc -g

PS C:\Users\young> npm install apidoc -g
C:\Users\young\AppData\Roaming\npm\apidoc -> C:\Users\young\AppData\Roaming\npm\node_modules\apidoc\bin\apidoc

> nodemon@2.0.9 postinstall C:\Users\young\AppData\Roaming\npm\node_modules\apidoc\node_modules\nodemon
> node bin/postinstall || exit 0

Love nodemon? You can now support the project via the open collective:
 > https://opencollective.com/nodemon/donate

npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@~2.3.2 (node_modules\apidoc\node_modules\chokidar\node_modules\fsevents):
npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for fsevents@2.3.2: wanted {"os":"darwin","arch":"any"} (current: {"os":"win32","arch":"x64"})

+ apidoc@0.28.1
added 183 packages from 124 contributors in 129.737s

配置apidoc.json

# cd 到patrol 的目录下创建apidoc.json, footer.md, header.md 文件
# *** 注意 ***
# 命令执行路径喝该文件所在路径要相同

创建header.md

### Description
天翼云 XXXX 系统 V1.1.0 API 文档

创建footer.md

**_reminder:_**  If you have any questions, please contact the developers

创建apidoc.json

{
  "name": "天翼云xxxx系统",
  "version": "1.1.0",
  "description": "",
  "title": "天翼云xxxx系统",
  "url": "http://ip-address:port",
  "header": {
    "title": "API V1.1.0",
    "filename": "header.md"
  },
  "footer": {
    "title": "",
    "filename": "footer.md"
  }
}

接口注释

class StaticRouteAPI(Resource):
    @catch_exception
    def get(self, uuid):
        """
        @api {get} /ctce/sdwan/<string:uuid>/route Gets the static route
        @apiDescription Get the static route info if the specified device
        @apiGroup ctce sdwan device
        @apiParam {String} uuid (required) unique id of device
        @apiParamExample {json} Request-Example
            {
                uuid: "bc61-2dc129bdc7c5-0210525003"
            }
        @apiSuccess (response) {String} unique id of device
        @apiSuccessExample {json} Success-Response:
        HTTP/1.1 200 OK
            {
                "code": 0,
                "message": "success",
                "result": [
                    {
                        "destination-prefix": "10.10.10.15/24",
                        "device-id": "bc61-2dc129bdc7c5-0210525003",
                        "id": "361bea05-c770-4087-bc61-2dc129bdc7c5",
                        "ip-protocol": "IPv4",
                        "next-hop": [
                            {
                                "next-hop": "10.10.10.14",
                                "out-going-interface": "wan1",
                                "precedence": 100
                            }
                        ]
                    }
                ]
            }
        """
        data = ctce.get_static_route(uuid)
        return jsonify(code=SUCCESS_ERROR_CODE, message='success', result=data)

注释：
-i 选择源代码所在的位置。如：apidoc -i myapp/
-o 选择生成的目标文件所在的位置
-t 为生成文件选择模板，
-h 帮助文档

注： apidoc 在 python代码中的语法是 """ command """
@api {method} path title 定义一个接口的简短标题（title）
eg: @api {post} /route create static route
@apiDescription description text 接口描述， 如暂无可用None
eg:
 @apiDescription Create static route 
   or 
  @apiDescription None 
@apiGroup group name 对api文档进行分组
eg: @apiGroup Edge
@apiVersion Number 当前接口的版本
eg: @apiVersion 1.1.0
@apiParam {type} field description   参数 type:参数类型; field: 字段名称; description 字段注释
eg:
@apiParamExample {type} tap title
@apiSuccess (response) {type} field descirption  返回值参数
eg:
@apiSuccess (response) {String} device_uuid  uuid of device
@apiSuccessExample {json} Success-Response:
HTTP/1.1 200 OK
{
    "code": 0,
    "message": "success"
}

npm install apidoc-markdown -g