接口文檔是描述如何與軟件系統(tǒng)中的特定接口進行交互的文檔，通常包含接口的名稱、描述、請求和響應的格式、參數(shù)、返回值、錯誤碼、調(diào)用示例等信息。它是開發(fā)人員在設計和開發(fā)軟件系統(tǒng)時必不可少的參考資料。
日常工作中，運用接口文檔最多的是前后端的同學，因為要遵守各自的規(guī)范流程，所有要提前訂好一個規(guī)范和流程，目的在于和前端對接的時候不至于太混亂。
舉個例子：在對接過程中，經(jīng)常會發(fā)生前端和后端聯(lián)調(diào)時候出現(xiàn)意見分歧。如果后端寫的接口不規(guī)范，設置沒有和前端統(tǒng)一一下就開始自己編寫代碼，就會出現(xiàn)和前端對接的時候會出現(xiàn)請求的值和返回的值出現(xiàn)不一致，代碼不嚴謹?shù)目雌饋碜屓祟^疼的問題，最后導致前端一直在反饋，每次開會都會瘋狂吐槽后端。而接口文檔其實就是前后端提前定義好的開發(fā)協(xié)議標準。
通過 API 文檔驅(qū)動開發(fā)流程
最近和組內(nèi)同事們溝通時，也聽到一個觀點：以“文檔驅(qū)動”的一種協(xié)作模式，比如“先開發(fā)，再維護文檔”和“口頭確認溝通”的方式，達到產(chǎn)品質(zhì)量和團隊協(xié)作率相應都得到提高。
在了解了這種協(xié)作模式之后，項目組負責人找了一個工具，希望可以是文檔的方式來推動工作，采用“文檔驅(qū)動”的方式來降低或者代替無效溝通的成本。
為 API 工作方式提供信息來源
API 文檔是人類和機器共同可讀的技術(shù)內(nèi)容，用于解釋某種特定場景下API 的工作原理及功能?？梢云鸬揭粋€雙重驗證的目的，為了最大效果化，API 文檔可以起著 API 工作方式的一個真正信息來源的作用。工具需要支持結(jié)構(gòu)化格式包含函數(shù)、參數(shù)、類等的詳細信息，便于開發(fā)人員和非技術(shù)人員/用戶正確理解。一般情況下，主要包括教程和示例，幫助用戶更好地理解不同部分如何協(xié)同工作。
什么是好的 API 文檔？
一個好的 API 文檔，除了內(nèi)容合理詳細之外，它的樣式和交互方式也要簡單易用。現(xiàn)在的 API 文檔基本基于網(wǎng)頁來展現(xiàn)，利用網(wǎng)頁的顯示特性，有一些比較常見的設計方式。在這里推薦一些適合作為 API 文檔展現(xiàn)要素的一些最佳實踐。
- 許多流行的工具在線發(fā)布他們的 API 文檔，以便第三方開發(fā)人員可以輕松訪問它們。以下是這些文檔如此有效的一些原因：在文檔中提供了示例代碼，以便用戶可以看到 API 在實踐中是如何工作的；
- 輕松找到常見問題的解決方案，以便忙碌的開發(fā)人員可以快速獲得所需的內(nèi)容；
- 不提供理解 API 及其工作方式之外的不必要信息。當用戶忙于工作并遇到問題時，他們需要可用的文檔，而不是無關的信息；
- 不需要設限知識水平；最簡單的概念和最困難的概念一樣得到充分解釋格式良好。內(nèi)容有條理且一致且易于閱讀。這減少了希望學習或解決問題的用戶的摩擦。
通過文檔工具進行協(xié)作辦公
使用文檔工具- Eolink Apikit 過程中，大部分的協(xié)作工作幾乎都是圍繞著 API 接口文檔來進行的，創(chuàng)建人通過創(chuàng)建 API 文檔之后，有訪問權(quán)限的人可以實時查看當前 API 的改動情況，通過 API 文檔發(fā)起 API 測試，設計 API test case，Mock API 數(shù)據(jù)，對 API 進行自動化測試等。
對 API 設置不同的狀態(tài)
Eolinke Apikit 將 API 的狀態(tài)劃分為以下幾種，方便成員在查看 API 文檔時了解 API 當前所處的
狀態(tài)。
- 已發(fā)布：API 已發(fā)布，可正常使用
- 設計中：等待或正在設計 API
- 待確定：API 已設計完成，等待相關成員確定 API 的內(nèi)容
- 開發(fā)：API 已確定內(nèi)容，等待或正在開發(fā)
- 對接：API 已開發(fā)完成，等待或正在對接
- 測試：API 已對接完成，等待或正在測試
- 完成：API 已測試完成，等待發(fā)布
- 異常：API 出現(xiàn)異常，需要盡快排查
- 維護：API 維護或升級中
- 廢棄：API 已廢棄，不可正常使用
通過對 API 幾種不同狀態(tài)的維護，讓組內(nèi)成員可以隨時 track API 當前的進度、狀態(tài)、一目了然于 API 目前處于什么階段以及完成的一個情況。
對文檔工具的要求
想要一個工具來處理所有類型的文檔是很自然的。考慮 API 文檔通常需要與研發(fā)團隊協(xié)作。將 API 文檔硬塞進其他文檔平臺顯然是不可以的。當研發(fā)團隊處于版本控制中，比如 Git，所以即使是復制粘貼到 CMS 的手動過程也不可能完全實現(xiàn)。隨著每次迭代對 API 進行更改，文檔需要隨著修改，生成 API 參考將確保避免許多潛在的麻煩。
Eolink Apikit 管理工具除了可以手動創(chuàng)建 API 外，還可使用快速導入功能為其創(chuàng)建 API 及其所需的文檔。創(chuàng)建 API 后，系統(tǒng)會管理新版本，使每次更新迭代版本都了如指掌。
對 API 文檔的可維護性
- 對于 API 文檔的可維護性應該保持像維護一個單獨項目一樣，使用 Eolink Apikit 工具每次以分支的形式進行更新，編輯人員在檢查文檔內(nèi)容的正確性和簡介之后，并由項目組成員進行 review。當 API 文檔發(fā)布后，后期維護也是同等的重要，主要體現(xiàn)在兩個方面：New feature 和廢棄功能；當發(fā)布新功能之前應該先發(fā)布文檔，并保證文檔通過了標準的 review 流程。然而廢棄掉的舊功能從文檔中移除，并建議在對應的位置給出廢棄功能提示和升級指南，確保使用舊功能的開發(fā)者進行升級工作。
- 作為開發(fā)?員，有的時候我們可能很容易忽視這?點。但是根據(jù)知識的偏差，假設我們的 API ?戶是程序員，他們知道我們所知道的，理解我們所理解的，但我們并不認為他們是最終?戶或客戶。要克服這種偏差，換位思考是設計好的 API 的關鍵思想。所以當你編寫下?個 API 時，把??放在客戶的?度，想象你想要的是什么，這時候你可能需要一個可以管理 API 文檔的工具，體現(xiàn)出 API 文檔的可維護性的價值。
接口文檔生成工具
國產(chǎn)接口測試和接口文檔生成工具 Eolink Apikit ，可以幫助我們在開發(fā)完接口之后對接口進行測試，完善 API 文檔后，當項目更新，API 需要進行迭代優(yōu)化，修改后的 API 文檔可設置通知，提升信息的時效性的同時，讓開發(fā)團隊快速了解 API 修改內(nèi)容或新功能。不同企業(yè)開發(fā)團隊規(guī)模不同，其中還包含測試團隊。為了能讓不同角色操作不同項目，權(quán)限設置格外重要。這樣可以確保 API 管理過程在開發(fā)階段盡早開始，幫助處理在開發(fā)完成之前需要進行的測試和改進工作。
關于一些可用性建議
API 管理目標： API 的管理目標圍繞著整個 API 的生命周期，開發(fā)團隊需要一個可靠的流程來對
API 進行系統(tǒng)化的管理，這其中包括詳細的 API 文檔與 API 版本控制等。版本控制和文檔： 出色的 API 管理工具除了可以手動創(chuàng)建 API 外，還可使用快速導入功能為其創(chuàng)建 API 及其所需的文檔。創(chuàng)建 API 后，系統(tǒng)會管理新版本，使每次更新迭代版本都了如指掌。
消息通知： 完善 API 文檔后，當項目更新，API 需要進行迭代優(yōu)化，修改后的 API 文檔可設置通知，提升信息的時效性的同時，讓開發(fā)團隊快速了解 API 修改內(nèi)容或新功能。
API 監(jiān)控： API 監(jiān)控可以實時查看 API 的健康情況，包括不同節(jié)點的 API，當項目發(fā)生錯誤，API 監(jiān)控可以幫助我們快速定位錯誤的 API，節(jié)省了大量時間成本。
并不是每個項目或企業(yè)都需要 API 管理平臺。但如果您需要一個 API 管理的解決方案，想讓 API 管理更加規(guī)范并流程化，可以了解文中所展示的 API 管理平臺- Eolink Apikit
