[TOC] ### 为前端同学占坑 > 随着Angular、Vue和react Native等前端框架的流行和发展，SPA项目逐渐成为应用趋势，前端页面的构建也多采用MVVM的模式，前后端开始做到真正的分离，对于前端来说，后端只需要提供API接口就行了。作为一名后端程序员，如何方便省事地为前端提供交互接口文档，成为了我们必须要考虑的问题。这里介绍一款Web API文档生成工具名为apidoc，可以根据代码注释生成静态html网页文档，不仅支持项目版本号，还支持api版本号，方便比较和阅读。 ### 安装 Win环境下安装方法： 1. 官网nodejs.org下载[nodejs](https://nodejs.org/en/download/) 2. 安装好后将npm 替换为淘宝镜像cnpm `C:\Users\Administrator>npm install -g cnpm --registry=https://registry.npm.taobao.org` 3. 使用cnpm安装apidoc `C:\Users\Administrator>cnpm install apidoc -g` ### 用法 > apidoc -i myproj/ -o mydoc/ [-c ./] -f ".*\.js$" > -i 表示输入，后面是文件夹路径 > -o 表示输出，后面是文件夹路径 > 默认会带上-c，在当前路径下寻找配置文件(apidoc.json)，如果找不到则会在package.json中寻找 "apidoc": { } > -f 为文件过滤，后面是正则表达式，示例为只选着js文件 > 与-f类似，还有一个 -e 的选项，表示要排除的文件/文件夹，也是使用正则表达式 ### 配置 新建apidoc.json文件，可参照[官方配置示例](http://apidocjs.com/#configuration) ~~~ { "name": "example", "version": "0.1.0", "description": "apiDoc basic example", "title": "Custom apiDoc browser title", "url" : "https://api.github.com/v1" } ~~~ 我的配置如下 ~~~ { "name": "APP项目接口", "version": "0.0.1", "description": "测试接口", "title": "APP项目接口", "url" : "http://www.apidemo.com/interface", "order": ["Home","User"], "template": { "forceLanguage": "zh_cn" } } ~~~ ### 操作 1.在含有apidoc.json的文件夹(例如apidemo)下新建myproj文件夹和mydoc文件夹，在myproj文件夹下新建demo.php(注意文件格式要保存为utf-8，否则生成的API文档带中文的注释会产生乱码),我的demo.php代码如下： ~~~ <?php namespace app\www\controller; class Demo { /** * @apiDefine UserNotFoundError * * @apiError UserNotFound The <code>id</code> of the User was not found * * @apiErrorExample Error-Response: * HTTP/1.1 404 Not Found * { * "error": "用户未找到" * } */ /** * @api {get/post} /demo/info 获取用户信息 * @apiName user-info * @apiGroup User * * @apiParam {int} id 用户ID * * @apiSuccess {String} firstname 用户姓 * @apiSuccess {String} lastname 用户名 * * @apiSuccessExample Success-Response: * HTTP/1.1 200 OK * { * "firstname": "John", * "lastname": "Doe" * } * * @apiUse UserNotFoundError */ /** * @api {get} /demo/edit 修改用户信息 * @apiName user-edit * @apiGroup User * * @apiParam {int} id 用户ID * @apiParam {String} firstname 用户姓 * @apiSuccess {String} firstname 用户姓 * @apiSuccess {String} lastname 用户名 * * @apiSuccessExample {json} 成功返回 * HTTP/1.1 200 OK * { * "code": 200, * "data": {}, * "msg": "xxx", * "url":"" * } * * @apiUse UserNotFoundError */ public function edit(){ //todo } /** * @api {get} /demo/list 列表接口 * @apiVersion 0.0.2 * @apiName article-list * @apiGroup Home * * * @apiParam {int} page=1 页数 * @apiParam {int} [pageSize=10] 分页大小 * @apiParam {String} keyword 关键词 * @apiParam {String} sortType 排序类型 * * @apiSuccess (data) {int} page 当前页 * @apiSuccess (data) {int} pcount 最后一页 * @apiSuccess (data) {int} count 总条数 * @apiSuccess (data) {array} data 数据 * * @apiSuccessExample {json} 成功返回 * HTTP/1.1 200 OK * { * "code": 200, * "data": {}, * "msg": "xxx", * "url":"" * } * @apiErrorExample {json} 失败返回 * HTTP/1.1 200 OK * { * "code": 5xx * "msg": "xxx" * } * */ public function list(){ //todo return ''; } } ~~~ 2.回到apidemo文件夹下，按住shift键并点击鼠标右键选择“在此处打开命令窗口”，在命令窗口中执行如下命令： > apidoc -i myapp/ -o mydoc/ 3.打开mydoc文件夹可以看到生成了含有index.html的网页文档，用浏览器打开index.html文件，效果图如下：  4.该demo代码我已上传到github，可[下载学习](https://github.com/scalerone/learnApiDoc/tree/master/demo5)。 ### 遇到的问题 问题描述： >在该静态文档下，选择相关接口，发送请求，收不到返回的json数据，打开浏览器F12中选择console可以看到，存在跨域问题。如下图所示： 解决办法： > 将生成的api文档mydoc文件夹放在访问接口的同域名下，通过域名访问index.html。即在thinkphp5项目中，把mydoc文件夹放在入口文件index.php的同级目录下，通过http://www.apidemo.com/mydoc/index.html访问。 ### 学习资料 apidoc相关参数详解，学习可参照官方教程和相关博客 1. [apidoc的介绍和使用](http://blog.csdn.net/lvbaolin123/article/details/52671677) 2. [使用apidoc 生成Restful web Api文档](http://blog.csdn.net/soslinken/article/details/50468896) 3. [ 官方教程](http://apidocjs.com/)