前言

當(dāng)下的web開發(fā)中，前后端分離的體制基本已經(jīng)成型，這時候一份好的API文檔對于前后端溝通來說是十分重要的橋梁。

但現(xiàn)實是，書寫API文檔對于后端開發(fā)人員來說一直是一件十分頭疼的事情，雖然有著諸如Java Doc、Api Doc這樣的工具，生成API文檔依然需要后端人員手動填充大量的內(nèi)容，而且生成的文檔可維護(hù)性差，稍有修改就需要重新執(zhí)行生成新的文件，或是依賴于某種語言和框架，不夠通用...

綜合長時間書寫API文檔的痛苦體驗，一個全新的思路誕生了，那就是把文檔生成這道工序從代碼中剝離出來，使用測試來生成文檔。

基于這樣的思路，不洗碗工作室開發(fā)了使用測試來生成和管理API文檔的工具一葉(Api Leaf)。

基于HTTP的接口測試

后端開發(fā)人員不可避免的需要對自己的接口發(fā)送模擬的HTTP請求，來測試結(jié)果。通常我們會使用POSTMAN這樣的工具來進(jìn)行測試。

實際上，一個成功的測試所包含的請求內(nèi)容和響應(yīng)內(nèi)容，本身就可以作為文檔的參考（很多文檔里都會附有這樣的請求和響應(yīng)示范）。事實上，在我們團(tuán)隊早期的開發(fā)工作中，也經(jīng)常利用POSTMAN測試后生成的COLLECTION來進(jìn)行前后端的溝通，它大概是下面這樣的：

但實際上這樣生成的測試用例集合可讀性非常差，而且不好維護(hù)和管理，于是我們又需要在測試完之后去手動的書寫文檔，再把測試用例復(fù)制進(jìn)文檔里當(dāng)做示范...一個復(fù)雜的API文檔就要書寫很久，實在是打擊后端開發(fā)人員的積極性。

基于測試結(jié)果提取API信息

仔細(xì)的分析一下，API文檔中所包含的內(nèi)容無非是請求和響應(yīng)字段有哪些，分別是什么含義，實際上這些內(nèi)容已經(jīng)包含在測試的請求和響應(yīng)體中了。

所以不妨來對這些信息進(jìn)行一些抽象，請求和響應(yīng)的數(shù)據(jù)一般都是JSON數(shù)據(jù)，前端在閱讀文檔時，真正關(guān)心的有以下的內(nèi)容：

• 字段的名稱，也就是json的key

• 字段值的類型，也就是json的value的type

• 字段值的描述，這是對字段更詳細(xì)的一些說明，包括一些表單的驗證規(guī)則等（并不是每個字段都必要的）

• 數(shù)據(jù)的結(jié)構(gòu)，主要是對象或者是數(shù)組之間的嵌套關(guān)系

那么這些值是否都可以從一個完整的測試數(shù)據(jù)中提取出來呢，如果可以的話，把這些工作交給代碼去生成，可就解放了后端人員的雙手和心智。

答案是肯定的，我們把文檔中的一項（表格中的一行）抽象成下面這樣一個對象:

{

key:...

type:...

description?:...

}

通過按照層級遍歷JSON對象的每一個屬性很容易得到它，key自然是自動填充的，type可以根據(jù)代碼推斷，只有description需要人手工去填寫，而這個字段還不是必要的...

剩下的問題是考慮遍歷之后如何去保留對象之間的層級關(guān)系，比如下面這個JSON響應(yīng)：

{

"code": 0,

"data": {

"problems": [

{

"id": 1001,

"title": "A+B（基本輸入輸出1）",

"difficulty": 2,

"source": "",

"submit": 3403,

"accepted": 1765,

"is_public": 1,

"created_at": "2014-01-17 00:18:19",

"updated_at": null,

"name": "basic",

"tags": [

{

"tag_title": "basic",

"tag_id": 1

}

]

}

],

"total_count": 576

}

}

最外層的對象中包含了code和data兩個屬性，data中又包含了一個名為problems的數(shù)組，problems中的每個對象又擁有諸多屬性...

想要記錄下結(jié)構(gòu)其實也并不復(fù)雜，我們只需要記錄下子屬性的父屬性就可以了。換句話說，你只要知道這個字段是隸屬于哪個字段的，總能順藤摸瓜一路摸清整個JSON的結(jié)構(gòu)，就好像樹這種數(shù)據(jù)結(jié)構(gòu)的遍歷一樣。

使用代碼進(jìn)行簡單的層級遍歷和篩選，最終可以得到像下面這樣的文檔結(jié)構(gòu)：

由于層級遍歷的順序，最終結(jié)果的排列順序也是從最外層向最內(nèi)層擴(kuò)充的，具有很高的可讀性。

最后我們需要對包含多個同樣模型的對象數(shù)組做個篩選，只保留它的第一個元素就足以生成文檔了。

整個測試的所有部分基本上都可以這樣處理，包括請求頭、query string、請求體、響應(yīng)頭、響應(yīng)體，根據(jù)需要來進(jìn)行組合，把所有測試的API集合在一起，最終就是一份完整的API文檔了。

使用一葉生成文檔

上述的思路已經(jīng)在我們的測試用工具一葉中實現(xiàn)了。利用這個工具，書寫API文檔的時間已經(jīng)被大大壓縮，一個API的文檔生成平均只需要幾秒鐘就可以解決了，現(xiàn)在讓我們來看看如何使用這套工具。

創(chuàng)建項目

一葉的文檔是根據(jù)項目生成的，因此在開始生成文檔前你需要先創(chuàng)建自己的項目，登錄注冊后的主面板上可以看到你所創(chuàng)建的項目和參與的項目

進(jìn)行測試

首先訪問一葉的網(wǎng)站： 并注冊登錄，在右上角的下拉菜單中，選擇“發(fā)起測試”后會跳轉(zhuǎn)到下面這個頁面：

這是使用JS和FETCH技術(shù)實現(xiàn)的在線的請求測試工具，使用起來的感覺和POSTMAN幾乎一樣。由于使用了和前端請求一樣的FETCH方式，使用它進(jìn)行測試你還可以檢查到一些其他的bug，比如請求的跨域問題等等。

輸入URL進(jìn)行測試，填寫好測試用的body和headers就可以發(fā)起請求，進(jìn)行測試，收到響應(yīng)后Response中將會顯示請求的header和body。

生成文檔

確定你測試的請求和響應(yīng)沒有異常之后，就可以立刻生成該API的文檔，點擊最下方的“生成文檔”按鈕就可以開始文檔的生成了，這時候一葉會根據(jù)JSON的內(nèi)容自動解析好文檔項的結(jié)構(gòu)，并以json的方式展示出來。

每個可能需要生成文檔的部分都會被自動解析成這樣的包含key,type,description三部分的結(jié)構(gòu)，其中只有description字段需要手動填寫（如果不需要也可以不填留空），對于不需要生成文檔的部分可以在左上角取消勾選來忽略。

填寫好必要的description字段后別忘了填寫API的基本信息：所屬的項目、名稱、以及分類（GROUP），最后點擊生成文檔，該API的文檔就完成了，這時候會顯示如下的預(yù)覽界面：

分享項目文檔

最終一個項目文檔的展示頁面如下：

提供了非常多的輔助篩選、定位、排序功能，方便前端人員的查閱

生成文檔后你需要把自己的項目文檔發(fā)送給前端使用，這非常的簡單，只要把查看文檔的鏈接復(fù)制分享就可以了。

一個項目的文檔將隨著你的添加和更改自動變化，你不用再擔(dān)心文檔的維護(hù)問題，只要做好測試，其他的一切都是自動的了。

其他

文檔的生成在較大型的公司中一般會使用根據(jù)框架專門編寫的自動化測試和生成工具，但是對于中小型開發(fā)團(tuán)隊來說，開發(fā)這樣的工具成本太高，代價太大，手工去書寫又耗費時間，這時候就非常適合使用一葉這樣的通用工具來生成和共享文檔。

本項目目前代碼開源在GitHub上，地址：https://github.com/MarkLux/ApiLeaf

基于PHP的Laravel框架開發(fā)，如果公司內(nèi)部對API有保密需要，也完全可以在內(nèi)部服務(wù)器中快速搭建一葉平臺進(jìn)行內(nèi)部測試交流。

目前本項目已經(jīng)經(jīng)過一次內(nèi)部測試，并且仍在持續(xù)開發(fā)中，歡迎廣大開發(fā)者試用并提出寶貴意見。