為什么要用apidoc
-
apidoc根據(jù)其自定義注釋語(yǔ)法自動(dòng)生成api文檔，我們只需要把代碼中的注釋按照其語(yǔ)法來(lái)寫(xiě)就能生成需要的文檔，不需要手動(dòng)寫(xiě)markdown。 -
apidoc生成的文檔相比markdown，漂亮直觀又實(shí)用。 - 如果API需要修改或者更新，直接修改代碼的注釋中即可。apidoc核心思路，文檔與代碼合一，修改代碼就是修改文檔，方便又實(shí)用。
- 可以配合
grunt使用，使自動(dòng)化生成文檔更加智能，支持多種語(yǔ)言。
0x01 安裝和配置apidoc
- 首先要確認(rèn)你的系統(tǒng)安裝了
nodejs，然后執(zhí)行npm install -g apidoc即可。 - 配置
apidoc，在你的項(xiàng)目下創(chuàng)建apidoc.json文件，apidoc.json說(shuō)明
{
"name": "測(cè)試APIs",
"version": "1.0.0",
"description": "接口測(cè)試",
"title": "test APIs",
"url" : "http://localhost:9220/sapi/v1/production_plan",
"sampleUrl" : "http://localhost:9220/sapi/v1/production_plan"
}
0x02 如何使用
apidoc是根據(jù)其自定義注釋語(yǔ)法來(lái)生成文檔的，語(yǔ)法可參考apidoc Params
下面是作者的一些注釋代碼，可以參考這個(gè)把注釋寫(xiě)到你的代碼相應(yīng)的位置：
/**
* @api {get} /test 接口測(cè)試
* @apiDescription 根據(jù)ID（id）獲取列表信息
* @apiGroup test APIs
*
* @apiParam {Number} id 任務(wù)ID
* @apiParam {Number} [page] 頁(yè)數(shù)
* @apiParam {Number} [perpage] 每頁(yè)的條數(shù)
*
* @apiParamExample {string} 請(qǐng)求參數(shù)格式:
* ?id=123&page=1&perpage=20
*
* @apiVersion 1.0.0
* @apiErrorExample {json} 錯(cuò)誤返回值:
* {
* "code": 10003,
* "msg": "ParametersError [Method]:get_tests參數(shù)錯(cuò)誤!",
* "error": {
* "id": "",
* "page": "",
* "perpage": ""
* },
* "status": "fail"
* }
* @apiSuccessExample {json} 正確返回值:
* {
* "code": 0,
* "msg": "OK ",
* "data": [
* {
* "id": "622051004185471233",
* "testCode": "000050",
* }
* ],
* "status": "ok",
* "count": "14"
* }
*/
-
@api定義API的請(qǐng)求方法、路徑和名字 -
@apiDescription定義API的描述 -
@apiGroup定義API的分組 -
@apiParam定義API的參數(shù) -
@apiParamExample參數(shù)請(qǐng)求的事例 -
@apiVersion版本 -
@apiErrorExampleAPI錯(cuò)誤示例 -
@apiSuccessExampleAPI正常示例
0x03 生成文檔
執(zhí)行命令apidoc -i src/ -o apidoc/
-
-i src/是把src文件夾下帶有apidoc語(yǔ)法注釋的代碼全部生成文檔 -
-o apidoc/是文檔的生成目錄
一切大功告成，打開(kāi)apidoc文件夾下的index.html文件
文檔界面
簡(jiǎn)書(shū)作者 小菜荔枝 轉(zhuǎn)載請(qǐng)聯(lián)系作者獲得授權(quán)
