文章目錄
- 一、前言
- 二、接口文檔線上平台
-
- 1.apizza
-
- 1.1 文檔導出html
- 1.2 導入Postman.json和Swagger.json檔案
- 2. YApi
-
- 2.1 源碼開源&免費&支援二次開發
- 2.2 [隻能]内網部署
- 2.3 支援自動化測試
- 2.4 支援導入 Postman HAR Swagger JSON
- 2.5 支援導出 html markdown json
- 3. RAP 2
-
- 3.1 導出 Postman Collection
- 3.2 支援 mockjs
- 4. eolinker
-
- 4.1 功能完善
- 4.2 付費功能
- 三、文檔線上平台
-
- 1. 語雀
- 2. 石墨文檔
- 3. Github的wiki
- 四、檔案管理平台
-
- 1. Github
- 五、總結
一、前言
作為一個公司的技術部門，就會涉及到一些文檔的對接，包括但不僅局限于
- 需求文檔
- 會議記錄
- 接口文檔
- 切圖示注
對接的部門，包括但不僅局限于
- 前端和後端
- 移動端和後端
- 設計和前端
- 設計和移動端
- 産品經理和開發
- 老闆和産品經理
那麼，在這些溝通中産生的文檔，該怎麼儲存、歸檔，該怎麼閱讀、使用，就成了團隊協作提升溝通效率中重要的一個環節。
接下來，我列舉了一些工具，供開發人員和項目管理人員選擇，根據自己的實際情況選出對應的解決方案。
二、接口文檔線上平台
這裡處理的問題是前端和後端互動，産生的一些接口文檔，這些文檔格式統一，但變更很快，并且修改之後看起來并不明顯，如果開發團隊有異地協作和遠端辦公，溝通又是個問題。
1.apizza
apizza的定位是api協作管理工具 ，官網位址為 https://apizza.net/
他的首頁是這樣的
實際使用界面是這樣的
emmmm，實際上就是一個線上版本的Postman…
有幾個亮點功能，如果你正好需要的話，可以酌情加分~
1.1 文檔導出html
導出的樣子是這樣的
很友善前端和移動端的同學閱讀，不知道比那些word文檔強到哪裡去了~
1.2 導入Postman.json和Swagger.json檔案
如果團隊内使用了Postman或者Swagger的話，就會讓操作更加連貫。
如果可以導出對應的檔案就好了~
2. YApi
YApi旨在為開發、産品、測試人員提供更優雅的接口管理服務。可以幫助開發者輕松建立、釋出、維護 API
網站上的特性如下
他的界面是這樣的
好吧，貌似開源的項目并不是都很好看…
2.1 源碼開源&免費&支援二次開發
注意的是，這個項目是開放源代碼的，也就意味着更安全，更可維護，你可以直接去回報bug，讓他做的更好。
項目位址為 https://github.com/ymfe/yapi
2.2 [隻能]内網部署
項目開源帶來的好處就是可以自己部署到内網上，保證資料的安全性。
同時YApi不提供公共的版本供大家注冊使用，也就是需要我們自己的團隊必須去部署。
2.3 支援自動化測試
2.4 支援導入 Postman HAR Swagger JSON
嗯！
2.5 支援導出 html markdown json
嗯！
3. RAP 2
為什麼不是RAP呢，因為"RAP1功能不會再增加啦，新項目推薦使用RAP2哦"~
RAP 2是一個可視化接口管理工具，淘寶團隊做的。
RAP1就不看了，直接看RAP2的網站。
經過注冊登入，RAP 2的結構更像是Github。
有一個單獨的狀态頁面展示全網的活躍度，說明你并不孤獨。
其中接口的傳回值是通過填寫對應的資料和規則生成的，而不是複制對應的json，這樣做更有利于測試工作。
3.1 導出 Postman Collection
看來大家都習慣于相容Postman，這也間接說明了Postman這個工具的成功~
3.2 支援 mockjs
mockjs也是淘寶團隊做的工具，“生成随機資料，攔截 Ajax 請求”。
4. eolinker
https://www.eolinker.com/
免費使用，API文檔管理、自動化測試、開發協作利器
在經曆過 注冊 -> 驗證郵箱 -> 填寫問卷 -> 幫助指南 之後，執行個體項目的接口編輯頁面是這樣的
從使用者的角度來講，這個的操作更加便利，雖然也是按Postman的樣式去做的~
4.1 功能完善
eolinker是一款完整的商業化的接口管理工具，基本用到的功能，在上面都能找到，并且操作和使用者體驗做的都不錯。
4.2 付費功能
功能完善的代價就意味着，如果你想要使用全部完善的功能，就要付費購買。
并且我們可以通過https://public.eolinker.com/index/EOLINKER%20AMS%20FUNCTION%20DETAIL%2020180520.pdf 來清晰的知道付費版的功能是哪些。
三、文檔線上平台
上面的平台的針對性比較高，是專業的做接口文檔的，還有一種是隻做文檔共享的，如果我們的目的是接口文檔管理，針對性就會差一些。
1. 語雀
語雀 https://www.yuque.com/ 是螞蟻金服做的一款文檔編輯共享平台。
由于文檔是可以全面公開的，是以，給我的感覺更像是簡書。 ????
語雀以知識庫作為文檔的載體，可以選擇線上編輯和分享給其他使用者，注意是不能導出檔案的哦。
如果作為内部工具使用的話，不是很推薦。
2. 石墨文檔
石墨文檔的側重點更傾向于大家一起修改檔案。
缺點也正是因為大家可以同時修改檔案，造成的檔案版本混亂。
石墨文檔更傾向于存儲一些定值的項目資料，而不是注重版本和變更的接口文檔。
3. Github的wiki
wiki有天生的優點
- 和項目綁定，這個項目的文檔就寫在這個項目的wiki中
- 版本控制和曆史回溯，因為和Github一樣的管理方式，保證了良好的版本控制
缺點也在于，如果這個文檔覆寫了多個項目，就隻好單獨開一個文檔的項目。
四、檔案管理平台
1. Github
本文中按範圍的涉及越來越廣，從局限使用和格式的專業接口管理平台，到限制文字不限制内容的文檔管理平台，最終就指向了不限制檔案格式的檔案管理平台，那麼這個非Github莫屬了~
我們可以用于管理
- 代碼項目
- 設計師設計和切圖
- 各種協定和文檔
- …
限制越少，對應的複雜度也就越多，如果控制的接口檔案格式排版不友好，帶來的舒适度也會直線下降，不過這些都是沒辦法的。
五、總結