放在前言
為什麼要做自動化 API 文件？
先來看我們內部程式碼的一張圖，我們在做業務的過程中，最苦惱的有 3 件事：
- 產品頻頻疊加需求
- 業務程式碼塊缺少註釋，鬼知道原業務程式碼是在幹嘛
- 介面層缺少文件，很多介面也會因為頻繁變更，從而導致文件的維護是一件相當費時的事情。
為了將這些很煩躁很苦惱的事解決掉（當然不鼓勵大家砍產品哈，主要是解決痛點 2、3 兩件事）可以選擇將註釋自動化生成 API 文件。
如何做？
實際上，現如今我們有很多自動生成 API 文件的選擇性，這裡主要講 apidocjs 是如何做的，其它自動生成 API 文件工具大同小異，只是 UI 頁面 & 註釋內容存在差異化，大家根據自己喜好選擇即可。
第一趴: apidocjs
- 安裝
// 專案安裝
npm install --save-dev apidoc
// 全域性安裝
npm install -g apidoc
複製程式碼- 建立 apidoc.json
{
"name": "文件中心",
"version": "1.0.0",
"description": "~",
"title": "文件中心",
"url": "http://localhost.com:2333",
"preview-url": "http://localhost.com:2333/apidoc/index.html"
}
複製程式碼- 配置 package.json
"apidoc": {
"title": "文件中心",
"url": "http://localhost.com:2333"
}
...
"scripts": {
...,
"apidoc": "apidoc -i src/ -o public/apidoc/"
}
複製程式碼- 說明 apidoc 命令列引數
| 引數 | 描述 |
|---|---|
| -f, --file-filters | 可以通過正則來選擇對哪些檔案進行監聽 .cs .dart .erl .go .java .js .php .py .rb .ts.舉例 ( 監聽.js & .ts 檔案): apidoc -f ".*\\.js$" -f ".*\\.ts$" |
| -i, --input | 需要 apidoc 監聽的目錄 舉例: apidoc -i myapp/ |
| -o, --output | 輸出目錄 舉例: apidoc -o apidoc/ |
| -t, --template | 使用模板輸出檔案。您可以建立和使用自己的模板。 舉例: apidoc -t mytemplate/ |
- API 示例
apidockjs 很有趣的是它的 @apiDefine(抽離公共塊) @apiUse(使用公共塊) @apiDefine 定義公共程式碼塊，然後可以通過@apiUse使用。@apiUse 使用@apiDefine定義好的程式碼塊。
/**
* @apiDefine CommonSuccess 成功響應欄位公共部分
* @apiSuccess {Number} errcode The success res code.
* @apiSuccess {Strng} message The res message.
*/
/**
* @api {get} /user/test
* @apiDescription 測試
* @apiGroup User
* @apiUse CommonSuccess
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* {
* "errcode" : 0,
* "message": "",
* "data" : [{
* "name" : "userName",
* "email" : "userEmail"
* }]
* }
* @apiSampleRequest http://localhost.com/user/test
* @apiVersion 1.0.0
*/
@get('/test')
async test() {
this.ctx.body = {
status: 200
};
}
複製程式碼- 使用
執行 yarn apidoc
在
public/apidoc 目錄下也生成了靜態檔案。預覽
index.html 第二趴: cz-conventional-changelog
- 安裝
// 在專案中安裝
npm i commitizen cz-conventional-changelog --save-dev
複製程式碼- package.json 配置
"scripts": {
...,
"commit": "git-cz"
}
"config": {
...,
"commitizen": {
"path": "cz-conventional-changelog"
}
}
複製程式碼- 示例
第三趴: 自動 run 起來
配置 package.json
"scripts": {
"commit": "git-cz",
"fast-commit": "npm run apidoc && npm run lint && git add public && git-cz",
"apidoc": "apidoc -i src/ -o public/apidoc/",
"lint": "tslint --fix -p tsconfig.json -t stylish",
...
}
複製程式碼
這樣配置後感覺就像四驅車配置了火箭馬達，爽翻了天。不管三七二十一，先自動生成文件，再做 tslint 最後完成 git commit 規範。
適合什麼階段搞？
我們要去分析現階段團隊痛點是什麼？
- 是程式碼太爛可讀性差？
- 是業務上沒有較好的突破點？
- 是測試在做功能測試很麻木？
- 是技術棧不統一換崗學習成本高？
……
我們的第一力量一定是搞團隊的痛點，剩下的力量就去搞比如說 API 文件、自動化構建工具、視覺化圖表等等。
如果你說現在痛點我也在搞，但還想搞一搞這些前端基礎建設，可以不？
答案是肯定的，你可以將基建當做自己技術成長的一部分，做好技術沉澱。
附:
{
"name": "open",
"version": "1.0.0",
"apidoc": {
"title": "文件中心",
"url": "http://localhost:2333"
},
"dependencies": {
"egg-view-assets": "^1.5.0",
"egg-view-nunjucks": "^2.2.0",
"midway": "^1.0.0"
},
"devDependencies": {
"@types/mocha": "^5.2.7",
"@types/node": "^10.5.5",
"commitizen": "^4.0.3",
"cross-env": "^6.0.0",
"cz-conventional-changelog": "^3.1.0",
"midway-bin": "1",
"ts-node": "^8.3.0",
"tslint": "^5.9.1",
"tslint-midway-contrib": "1",
"typescript": "^3.5.0",
"umi": "2.10.7",
"umi-plugin-ga": "^1.1.3",
"umi-plugin-react": "^1.1.1"
},
"engines": {
"node": ">=10.16.0"
},
"scripts": {
"commit": "npm run apidoc && npm run lint && git add public && git-cz",
"apidoc": "apidoc -i src/ -o public/apidoc/",
"debug": "cross-env NODE_ENV=local midway-bin debug --ts",
"lint": "tslint --fix -p tsconfig.json -t stylish",
"cov": "midway-bin cov --ts",
"ci": "midway-bin cov --ts",
"build": "midway-bin build -c",
"start": "cross-env NODE_ENV=local midway-bin dev --ts --port=10000"
},
"config": {
"build": {
"deps": "isolation"
},
"docker": {
"os": 7
},
"commitizen": {
"path": "cz-conventional-changelog"
}
},
"midway-bin-build": {
"include": [
"app/public",
"app/view",
"config/manifest.json"
]
},
"prettier": {
"singleQuote": true
},
"license": "MIT"
}
複製程式碼