簡介
我相信很多編寫後臺介面的同學們都跟我一樣，對於介面文件的編寫頭痛不已：編寫文件費時、費力，實在是打擊開發者的開發熱情，尤其是在中小型專案的敏捷開發，往往編寫文件花的時間比介面開發的時間還長。
對於大型專案和成熟團隊，一般都會有成熟的介面自動化測試工具，集介面測試、自動構建和mock資料一體，但是中小型開發團隊（比如學生組織）往往沒有搭建類似平臺的能力。
於是很多人索性不留文件了，但這又會增加前後端的溝通成本，降低整個團隊的工作效率。
正所謂“懶，是人類進步的第一動力”，本著儘可能減少文件編寫工作的偷懶目的，我嘗試開發了這款文件生成工具和管理平臺：ApiLeaf，如果你也是小型團隊中的後端開發者，也和我一樣不喜歡寫文件，就來看看它能不能幫到你吧！
核心思路
所謂API文件，無非是對於介面 請求 => 響應 這個過程的一個詳細描述和說明，而對於後端開發者而言，這個流程正是我們日常測試介面的過程，那麼只要能夠將這個測試過程記錄並重放，附上一些必要的說明，不就可以作為文件使用了嗎？
舉個例子，我們現在有一個計算 A + B 的介面，請求URL為http://localhost:8080/add，需要對它做一次測試，於是我們POST過去下面的資料：
{
"a": 1,
"b": 2
}
複製程式碼接著成功收到服務端的響應：
{
"code": 0,
"result": 3
}
複製程式碼介面的測試完成了，讓我們看看從這個過程中，都可以拿到哪些資料：
- 請求的URL
- 請求的方法Method
- 請求頭Headers
- 請求體Body的結構
- 一個正確的請求示範
以及
- 響應頭Headers
- 響應體Body的結構
- 一個正確的響應示範
根據這些內容已經完全足夠生成對應的介面的文件了，通常情況下只需要對Headers和Body中的各個欄位新增一些基本的描述就可以生成一份相當詳盡的文件.
ApiLeaf正是基於這樣一個思路，只要你在ApiLeaf上進行介面的測試，它就能記錄測試過程中的請求和響應資料，並且自動構建文件的基礎結構，大多數情況下你只需要補充一些基本描述（如果你使用了下文介紹的資料字典功能，甚至都不用填寫描述），就能快速地生成文件。
文件自動生成示範
廢話說了不少，不如來上手試試吧，首先訪問ApiLeaf，註冊並登陸你的賬號，然後點選首頁的主皮膚進入你的個人皮膚。
個人皮膚中提供了文件的管理介面，在開始嘗試文件自動生成之前，我們需要先建立一個專案。
在我建立的專案皮膚中，點選新建專案來建立一個專案，你只需要填寫一下專案名和描述就可以了：
接下來點選右上角的下拉選單，選擇發起測試即可進入HTTP測試皮膚，你會看到一個類似POSTMAN的介面。
現在我們來進行介面測試吧，以我本地的一個測試登入介面為例，這個介面接收一個login_name和一個password，成功後返回登入的使用者基本模型，我們補充好請求的URL和Body，然後就可以傳送請求進行HTTP測試了：
Api Leaf使用fetch來傳送這個請求，因此你可以用它來測試本地的介面，並且可以最大程度的模擬前端請求的真實環境，不過需要稍微注意一下跨域問題。
如果測試成功，你便可以在下方的Response皮膚中看到伺服器所返回的響應內容了：
如果測試失敗，無法獲取響應，可以開啟瀏覽器的控制檯追蹤fetch請求的異常原因。
現在我們就可以點選生成文件進入介面文件的編輯頁面了
首先我們需要補充一下介面的基本資訊，選擇該介面所屬的專案(生成後這個介面的文件將自動歸入該專案的總文件中)，URL和METHOD已經自動填充好了，補充一下名稱、描述即可。你還可以給介面填寫一個組名，用於在整個專案中進行介面的分類管理，這在專案介面很多的時候還是還是非常有用的。
接下來我們會看到很多的JSON編輯器，ApiLeaf會把從剛才的測試中拿到的資料分為以下7個部分，並自動填入到對應部分的編輯器中:
- API請求頭部（Headers）
- API請求引數（QueryString）
- API請求體（Body）
- API請求示範
- API響應頭（Headers）
- API響應體（Body）
- API響應示範
以剛才的測試為例，響應體編輯框中將會填入如下內容
[
{
"body_key": "code",
"body_type": "integer",
"body_description": ""
},
{
"body_key": "user",
"body_type": "object",
"body_description": ""
},
{
"body_key": "user.id",
"body_type": "integer",
"body_description": ""
},
{
"body_key": "user.name",
"body_type": "string",
"body_description": ""
},
{
"body_key": "user.sex",
"body_type": "string",
"body_description": ""
},
{
"body_key": "user.age",
"body_type": "integer",
"body_description": ""
}
]
複製程式碼ApiLeaf會將響應JSON中所有的key都抽離，構建層級關係（以.分割）並自動推斷他們的資料型別，你所需要做的只有檢查body_type是否正確，並且補充body_description欄位說明即可。
對於其他部分的內容，也會生成類似的JSON並填入對應的編輯器中，你只需要像做填空題一樣將他們補充完整。對於不需要的部分，可以取消勾選，這樣文件中就不會包含響應部分的內容，比如這個API中我只需要勾選請求體，響應體及其示範就足夠了。
需要注意的是，編輯框中的內容必須是合法的JSON，並且對於每個欄位的key都有要求，所以請不要隨便修改內含物件的結構，否則可能會引起錯誤（至於為什麼以JSON的方式填充，當然是因為這樣就可以偷懶不用做介面了。。）
完成這些簡單的填空題之後，文件就可以生成了，你會看到這個API文件的預覽介面：
提供請求和響應兩個標籤頁分別展示相應的說明。
至此，一個結構的文件生成就完成了，理想的情況下，測試+生成文件的過程不超過1分鐘，還是非常方便的。
如果你覺得這樣還是麻煩，不想填這麼多填空題，可以看看下面的資料字典部分，如果合理使用，你甚至可以不用填寫任何內容就生成完整的文件！
資料字典與自動匹配
資料字典，是指在一個專案中頻繁使用的基本資料結構，比如剛才測試專案中的User物件，作為使用者資料的基本定義，可能在很多介面中都會用到，如果使用Api Leaf自動生成文件，很可能需要重複填寫多次User各個欄位的說明，這是我們不能接受的。
Api Leaf的思路是，將常用的資料結構建立成資料字典並儲存到專案中去，一方面可以方便前端人員快速獲取常用的資料結構定義，另一方面可以在資料結構重複出現時，自動匹配相關的字典，這樣就減少了重複編寫說明的過程。
說了這麼多，我們還是舉個例子來看看資料字典是如何使用的吧：
建立一個資料字典
進入指定專案的文件檢視頁面，點選頂部導航欄的資料字典即可進入資料字典的列表頁面，然後點選新增新字典按鈕進入資料字典的編輯頁面：
在編輯頁面填寫好資料字典的型別名和描述（注意一個專案中不能有兩個型別名相同的資料字典）後，可以通過手動新增的方式補充資料字典的各個欄位定義和說明，也可以從一個示範的JSON中解析出一個資料字典。
舉個例子，我們使用剛才響應中返回的User物件JSON來建立這個資料字典：
點選解析後，就能夠自動補充所有的欄位名和型別了，你需要手動檢查這些型別是否正確，並補充好相應的說明：
最後點選Done按鈕就可以生成一個完整的資料字典了。
自動匹配
現在我們有了一個資料字典，讓我們來看看如何使用自動匹配功能吧。
假設現在專案中多了另一個介面/user/{id}/profile，通過這個介面可以獲取指定使用者的個人資訊（也就是他的User模型），然後我們進行一次測試，得到下面的響應:
{
"code": 0,
"user": {
"id": 17,
"name": "lumin",
"sex": "male",
"age": 20
}
}
複製程式碼現在我們需要生成文件了，這時候你發現這個user型別我們在之前的登入介面裡已經定義過一次了，難不成又要重新寫一遍每個欄位的描述？
答案當然是NO，只要你已經將這個資料結構定義進了資料字典，那麼在這一步你就不必填寫任何的body_description欄位，直接點選生成文件，然後進入專案文件的檢視頁面，你會發現在響應的說明欄位，多了幾個按鈕...
接下來點選這個按鈕，神奇的事情發生了：Api Leaf將根據所選欄位的所有key，自動去專案的資料字典中匹配最可能的資料定義，在這個例子中，我們將可以得到匹配率達到100%的User資料定義，沒錯，我們要的就是它了！
匹配功能將會盡可能地搜尋資料字典中最類似的結構，但是也會出現搜尋不到或者匹配率很低的情況，比如下面這樣：
匹配到的欄位將會加粗顯示。
當匹配率低於60%的時候，很有可能這並不是你需要的資料定義，這時候還是老老實實地補充資料字典或者欄位定義吧~
只要定義好常用的資料字典，生成文件時就會省去很多力氣，因此建立好專案的基本資料定義（比如資料庫表結構）後，就把他們補充到資料字典中去吧！
注意
資料字典目前暫不支援巢狀的層級欄位定義，匹配結果也僅供參考，建議前後端在使用此功能前先提前做好溝通。
一個完整的文件結構
使用Api Leaf建立一個專案文件的基本流程已經介紹完了，下面我們站在前端/客戶端開發者的角度，看看一個完整的專案文件能夠提供哪些資訊。
你可以點選此處檢視官方提供的一個簡單示範文件。
Api Leaf中一個完整的專案文件包括以下3部分：
- API介面文件：由HTTP測試生成並聚合
- 狀態碼列表：專案中使用到的各種狀態碼
- 資料字典：常用的資料結構定義
通過頂部的導航欄可以快速在三部分間切換，另外每個部分都提供了左側的導航欄，用於快速定位相關定義的位置：
其中API介面文件部分還提供了分組和排序、篩選等功能，為了方便閱讀人員找到文件，我們還提供了收藏功能，可以儲存最近經常使用的文件。
其他
Api Leaf還提供了諸如團隊協作等其他功能，在此不一一贅述，請檢視說明文件瞭解更多細節。
這是我做的第一個開源工具，更多的是站在自己團隊的使用角度上進行的設計和開發，但我相信大多數和我們團隊一樣的中小型敏捷開發團隊，尤其是學生團隊，需要這樣一款工具來方便成員之間的溝通和交流。
因為是個人獨立開發，所以在頁面美觀、使用邏輯方面尚有需要打磨的地方，後面我也會持續更新和優化相關功能。
歡迎廣大開發者試用並提出寶貴意見！
- 作者：劉明@不洗碗工作室
- github：https://github.com/MarkLux/ApiLeaf
順便一提，我在頁面上埋了幾個彩蛋，有興趣的同學可以找找看~