放在前言

为什么要做自动化 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"
}