Background

一直在找一個可以簡單產生API Document的工具. 當然產生出來的文件也要好看啦(其實這才是重點), 所以找到了APIDOC這個套件. 覺得還不錯. 就紀錄一下怎麼操作.

Install

$ npm install apidoc -g

Start

那自己是把APIDOC當作一種寫API docs的Tool, 所以我可能用PHP開發程式. 但我卻用 Javascript or python 的檔案來產生 API docs這樣. 反正不衝突. 所以首先到你的開發資料夾接著創造一個 docs 資料夾來放你的api文件.

$ cd path/to/myapp
$ mkdir docs
$ cd docs
$ touch apidoc.json
$ mkdir src 
$ mkdir out

解釋一下各個檔案 & 資料夾有何目的.

  • apidoc.json: 使用 APIDOC 所需的基本設定檔.
  • src: 放我寫 api docs 的原始檔
  • out: 透過 APIDOC 轉出的 html 的相關檔案

以上的用法沒有一定要照我的用, 依據你自己個人的喜好即可.

apidoc.json

{
  "name": "ShoWe",
  "version": "0.1.0",
  "description": "Showe Restful API Document",
  "title": "ShoWe APIS",
  "url" : "https://showe.show"
}

src/basic.py

"""
@apiDefine UserNotFoundError
@apiError UserNotFound The id of the User was not found.
@apiErrorExample Error-Response:
    HTTP/1.1 404 Not Found
    {
        "error": "not found in databse"
    }
"""


"""
@api {get} /user Request User information
@apiName GetUser
@apiGroup Basic
@apiVersion 0.1.0

@apiParam {Number} id Users unique ID.
@apiParamExample {json} Request-Example:
    {
        "id": 4711
    }

@apiSuccess {String} firstname Firstname of the User.
@apiSuccess {String} lastname  Lastname of the User.

@apiSuccessExample Success-Response:
    HTTP/1.1 200 OK
    {
       "firstname": "Paul",
       "lastname": "Liang"
    }

@apiUse UserNotFoundError
"""

Run

$ cd path/to/myapp/docs
$ apidoc -i ./src -o ./out

跑完之後會看到 out 裡面多了許多檔案. 在瀏覽器中打開 index.html, 會出現如下圖所示的東西, 那就大功告成了. 剩下的就你自己去運用了.

Reference