武夷 | 搞定自动化 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"
}

复制代码