團隊高效率協做開發的祕密武器-APIDOC

團隊高效率協做開發的祕密武器

1.前言

在團隊協做開發中，不知道各位有沒有遇到這樣的問題：

l 新人接手了項目代碼，因沒有項目文檔，只能靠追蹤路由，尋讀代碼分析業務邏輯

l 前端同窗寫好了頁面，苦等後端接口規則，來寫交互請求，獲取數據

l 測試同窗寫測試用例，因項目還沒完成，而遲遲沒法開工

如何愉快地解決以上問題呢？答案就是它——APIDOC。

2.APIDOC是什麼

APIDOC是一款Web API文檔生成工具，能夠根據代碼註釋自動生成靜態html網頁文檔，不只支持項目版本號，還支持接口版本號，接口版本更新升級後，文檔接口能夠很方便地對比閱讀。像這樣的接口文檔生成工具備不少，如Java語言有Javadoc、PHP語言有PHPDoc、Python語言有Pydoc等，爲何要選擇用它呢，由於它跨語言，無論你是用js、ruby、java、php、python、c#…，只要按規則寫好註釋，先後端兄弟都能用。讓咱們一塊兒來見證它的強大之處吧。

3.先看看使用效果

總體一覽~

 

圖1

接口變動啦，比對閱讀一下，清晰明白~

 

 

圖2

看看返回數據，測試一發，能夠開始寫測試用例啦~

 

 

圖3

4.具體實現流程

0x01 安裝

Windows環境下安裝方法：

1. 官網nodejs.org下載nodejs
2. 安裝好後將npm 替換爲淘寶鏡像cnpm

npm install -g cnpm --registry=https://registry.npm.taobao.org

3.使用cnpm安裝apidoc

cnpm install apidoc -g

0x02 用法

apidoc -i myproj/ -o mydoc/ [-c ./] -f ".*.js$"

-i 表示輸入，myproj是項目文件夾路徑

-o 表示輸出，mydoc是要生成的接口文檔路徑

默認會帶上-c，在當前路徑下尋找配置文件(apidoc.json)

-f 爲文件過濾，後面是正則表達式，示例爲只選js文件

與-f相似，還有一個 -e 的選項，表示要排除的文件/文件夾，也是使用正則表達式

0x03 配置

新建apidoc.json文件，可參照官方配置示例

{
  "name": "example",
  "version": "0.0.1",
  "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.api.com/v1",
  "sampleUrl" : "http://www.api.com/v1",
  "order": ["User","Article"],

}

　　

配置屬性簡單介紹

name：項目名稱 

version：項目版本 

description：項目介紹 

title：瀏覽器顯示的標題內容 

url：請求的前綴，例如https://api.github.com/v1 

sampleUrl：若是設置了，則在api文檔中出現一個測試用的from表單 

order：用於配置輸出接口組的順序

0x04 操做

1.在含有apidoc.json的文件夾(例如myproj)下新建myapp文件夾和mydoc文件夾，在myapp文件夾下新建user.php(注意文件格式要保存爲utf-8，不然生成的API文檔帶中文的註釋會產生亂碼),個人user.php部分代碼以下：

<?php

class User

{

/**

* @api {POST} /register 註冊用戶
* @apiGroup User
* @apiVersion 0.0.2
* @apiDescription 用於註冊用戶
* @apiParam {String} account 用戶帳戶名 
* @apiParam {String} password 密碼
* @apiParam {String} mobile 手機號
* @apiParam {int} company = 0  是否註冊企業用戶 0 普通用戶 1 企業用戶
* @apiParam {String} [recommend] 邀請碼
* @apiSampleRequest http://www.api.com/server.php
* @apiParamExample {json} 請求樣例：
*                ?account=test&password=11223344&mobile=182xxxx2345&company=0&recommend=
* @apiSuccess (200) {String} msg 信息
* @apiSuccess (200) {int} code 0 表明無錯誤 1表明有錯誤
* @apiSuccessExample {json} 返回樣例:
*                {"code":"0","msg":"註冊成功"}

*/

    public function register () { # code... }

/**

* @api {POST} /login 用戶登陸
* @apiGroup User
* @apiVersion 0.0.1
* @apiDescription 用於用戶登陸
* @apiParam {String} userName 用戶名
* @apiParam {String} password 密碼
* @apiParamExample {json} 請求樣例：
*                ?userName=張三&password=11223344
* @apiSuccess (200) {String} msg 信息
* @apiSuccess (200) {String} code 0 表明無錯誤 1表明有錯誤
* @apiSuccess (200) {String} user 用戶信息
* @apiSuccess (200) {String} userId 用戶id
* @apiSuccessExample {json} 返回樣例:
*    {"code":"0","msg":"登陸成 功","userId":"1"}

*/

   public function login() { # code... }

}

　　

2.回到myproj文件夾下，按住shift鍵並點擊鼠標右鍵選擇「在此處打開命令窗口」，在cmd命令窗口中執行以下命令：

apidoc -i myapp/ -o mydoc/

3.打開mydoc文件夾能夠看到生成了含有index.html的網頁文檔，用瀏覽器打開index.html文件便可瀏覽文檔效果圖。

5.遇到的問題

問題一：

在瀏覽器打開靜態文檔下，選擇相關接口，發送請求，收不到返回的json數據，打開瀏覽器F12中選擇console能夠看到，存在跨域問題。

解決辦法：

將生成的api文檔mydoc文件夾放在訪問接口的同域名下（如使用效果圖圖3），經過域名訪問該index.html文件。

問題二：

使用效果圖中的接口組名（@apiGroup參數對應值）-「User」和「Article」換成中文後，在瀏覽器中打開顯示爲亂碼。

解決辦法：

主要是 @apiGroup 不支持utf-8 字符串，僅支持ascii碼。官方有個辦法能夠實現utf-8字符串放置在@apiGoup 中。 代碼以下：

/**
 * @apiDefine User 用戶接口
 */

/**
 * @api {POST} /login 用戶登陸
 * @apiGroup User
*/

解決效果

  

圖4

 

6.總結

以上只是拋磚引玉，apidoc還有更多的用法，具體的介紹能夠去官網查看，快來動手練練吧，掌握這款工具，帶領團隊吃雞，無往而不利 。