團隊高效率協作開發的秘密武器
已更新：可以在內網服務器中搭建一個yapi，感覺更好用
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環境下安裝方法：
- 官網nodejs.org下載nodejs
- 安裝好后將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還有更多的用法，具體的介紹可以去官網查看，快來動手練練吧，掌握這款工具，帶領團隊吃雞，無往而不利 ，
轉載請註明出處，本文鏈接：https://www.uj5u.com/qita/69541.html
標籤：其他
上一篇：程式員最應該掌握的技術