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