Python的apidoc操作

目錄

• 前言
• apidoc的安裝
• Python文件定義接口信息
• apidoc.json文件
  • 栗子1
  • 栗子2
• 生成apidoc網頁文件

---

前言

• 操作系統win10
• 時間2019年02月
• Python版本：Python 3.5.2
• Nodejs版本：node v8.9.3
• 參考網址1
• 參考網址2
• 參考網址3

apidoc的安裝

npm install apidoc -g

-g參數表示全局安裝，這樣哪兒都能用了哦

Python文件定義接口信息

在對應的函數添加apidoc接口的定義描述，包括但不限於以下代碼

def login():
    """
    @api {POST} http://127.0.0.1:8000/login/ 登錄操作
    @apiVersion 0.0.1
    @apiName login
    @apiGroup User
    @apiDescription 這里可以描述一下這個函數的具體操作
    這一行也是可以描述的

    @apiParam {String} name 姓名
    @apiParam {String} password 密碼

    @apiSuccess {Object} status 狀態碼
    @apiSuccess {Object} msg 簡略描述

    @apiSuccessExample Response-Success:
        HTTP 1.1/ 200K
        {
            'status': 0,
            'msg': 'success'
        }
    @apiErrorExample Response-Fail:
        HTTP 1.1/ 404K
        {
            'status': 1,
            'msg': 'Fail'
        }
    """
    pass


def index():
    """
    @api {GET} http://127.0.0.1:8000/index/ 主頁操作
    @apiVersion 0.0.1
    @apiName index
    @apiGroup User
    @apiDescription 這里可以描述一下這個函數的具體操作
    這一行也是可以描述的

    @apiParam {Data} name 姓名

    @apiSuccess {Object} status 狀態碼
    @apiSuccess {Object} msg 簡略描述

    @apiSuccessExample Response-Success:
        HTTP 1.1/ 200K
        [
            {
                'id': 1,
                'name': '張三'
            }，
            {
                'id': 2,
                'name': '李四'
            },
            {
                'id': 3,
                'name': '王五'
            }
        ]

    @apiErrorExample Response-Fail:
        HTTP 1.1/ 404K
        {
            'status': 1,
            'msg': 'Fail'
        }
    """
    pass

apidoc.json文件

栗子1

{
  "name": "我的apidoc示例",
  "version": "0.0.1",
  "description": "這是一句描述，描述了api文檔",
  "title": "API DOC EXAMPLE"
}

栗子2

這種栗子中需要在apidoc.json文件的當前路徑下分別新建header.md和footer.md文件
apidoc.json

{
  "name": "example",
  "version": "0.1.0",
  "description": "apidoc test1",
  
  "header": {
    "title": "這不是頭",
    "filename": "header.md"
  },
  "footer": {
    "title": "這不是尾",
    "filename": "footer.md"
  }
}

header.md

# Example text from header.md

This text is from file "header.md".

## <span id="api-example-for-a-submenu-entry">HowTo include</span>

In your projects "package.json" you can set "apidoc.header" with a title and a filename to include this file into your documentation.

This example attempts to integrate "header.md" and "footer.md".

    {
      "name": "example",
      "version": "0.3.0",
      "description": "apidoc example project.",
      "apidoc": {
        "header": {
          "title": "My own header title",
          "filename": "header.md"
        },
        "footer": {
          "title": "My own footer title",
          "filename": "footer.md"
        }
      }
    }

footer.md

# Example text from footer.md

This text is from file "footer.md".

## HowTo include

Watch header.md for further information.

生成apidoc網頁文件

apidoc -i 代碼所在路徑 -o 生成文件的路徑

此時會在指定的生成文件路徑中生成一個apidoc的文件夾，里面的index.html文件就是啦啦啦啦~~~