ApiLeaf·多是史上最省事的文檔生成工具

簡介

我相信不少編寫後臺接口的同窗們都跟我同樣，對於接口文檔的編寫頭痛不已：編寫文檔費時、費力，實在是打擊開發者的開發熱情，尤爲是在中小型項目的敏捷開發，每每編寫文檔花的時間比接口開發的時間還長。

對於大型項目和成熟團隊，通常都會有成熟的接口自動化測試工具，集接口測試、自動構建和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部分：

1. API接口文檔：由HTTP測試生成並聚合
2. 狀態碼列表：項目中使用到的各類狀態碼
3. 數據字典：經常使用的數據結構定義

經過頂部的導航欄能夠快速在三部分間切換，另外每一個部分都提供了左側的導航欄，用於快速定位相關定義的位置：

其中API接口文檔部分還提供了分組和排序、篩選等功能，爲了方便閱讀人員找到文檔，咱們還提供了收藏功能，能夠保存最近常用的文檔。

其餘

Api Leaf還提供了諸如團隊協做等其餘功能，在此不一一贅述，請查看說明文檔瞭解更多細節。

這是我作的第一個開源工具，更多的是站在本身團隊的使用角度上進行的設計和開發，但我相信大多數和咱們團隊同樣的中小型敏捷開發團隊，尤爲是學生團隊，須要這樣一款工具來方便成員之間的溝通和交流。

由於是我的獨立開發，因此在頁面美觀、使用邏輯方面尚有須要打磨的地方，後面我也會持續更新和優化相關功能。

歡迎廣大開發者試用並提出寶貴意見！

• 做者：劉明@不洗碗工做室
• github：https://github.com/MarkLux/ApiLeaf

順便一提，我在頁面上埋了幾個彩蛋，有興趣的同窗能夠找找看~