apidoc核心思路，文档与代码合一，修改文档，方便又实用-docx文件怎样打开

为什么要用apidoc

apidoc根据其自定义注释语法自动生成api文档，我们只需要把代码中的注释按照其语法来写就能生成需要的文档，不需要手动写markdown。
apidoc生成的文档相比markdown，漂亮直观又实用。
如果API需要修改或者更新，直接修改代码的注释中即可。apidoc核心思路，文档与代码合一，修改代码就是修改文档，方便又实用。
可以配合grunt使用，使自动化生成文档更加智能，支持多种语言。

0x01 安装和配置apidoc

首先要确认你的系统安装了nodejs，然后执行npm install -g apidoc即可。

配置apidoc，在你的项目下创建apidoc.json文件，apidoc.json说明

{ "name": "测试APIs", "version": "1.0.0", "description": "接口测试", "title": "test APIs", "url" : "http://localhost:9220/sapi/v1/production_plan", "sampleUrl" : "http://localhost:9220/sapi/v1/production_plan"}

0x02 如何使用

apidoc是根据其自定义注释语法来生成文档的，语法可参考apidoc Params

下面是作者的一些注释代码，可以参考这个把注释写到你的代码相应的位置：

/*** @api {get} /test 接口测试* @apiDescription 根据ID（id）获取列表信息* @apiGroup test APIs** @apiParam {Number} id 任务ID* @apiParam {Number} [page] 页数* @apiParam {Number} [perpage] 每页的条数** @apiParamExample {string} 请求参数格式:* ?id=123&page=1&perpage=20** @apiVersion 1.0.0* @apiErrorExample {json} 错误返回值:* {* "code": 10003,* "msg": "ParametersError [Method]:get_tests参数错误!",* "error": {* "id": "",* "page": "",* "perpage": ""* },* "status": "fail"* }* @apiSuccessExample {json} 正确返回值:* {* "code": 0,* "msg": "OK ",* "data": [* {* "id": "622051004185471233",* "testCode": "000050",* }* ],* "status": "ok",* "count": "14"* }*/