武夷 | 搞定自動化 API 文檔

放在前言

爲何要作自動化 API 文檔？

先來看咱們內部代碼的一張圖，咱們在作業務的過程當中，最苦惱的有 3 件事：

• 產品頻頻疊加需求
• 業務代碼塊缺乏註釋，鬼知道原業務代碼是在幹嗎
• 接口層缺乏文檔，不少接口也會由於頻繁變動，從而致使文檔的維護是一件至關費時的事情。

爲了將這些很煩躁很苦惱的事解決掉（固然不鼓勵你們砍產品哈，主要是解決痛點 二、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"
}

複製代碼