[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/)