Java接口文檔進化史：一步步解放雙手
可能現在的小程序員聽到以前還有人用過 word 來做接口文檔，會驚訝得不行，但在前后端分離推行的早期，確實沒有那么多趁手好用的接口文檔工具。
互聯網發展到現在，接口文檔也經歷了從簡單的word到markdown，到swagger，到Apifox 等逐步進化的方式，變得越來越美觀，越來越規范，也支持越來越多的功能輔助調試。
接下來給大家盤點一下這些年接口文檔的進化歷程。
一、接口文檔的幼年體：word
一開始是前后端分離，后端得告知前端接口的各項信息，方便前端調用。那需要提供的信息也就那些，就用 word 寫吧，于是就有了這樣的接口文檔：
問題似乎解決了，但項目嘛，是不停修改和迭代的，這樣會導致：
這份接口文檔是隨著項目進行頻繁改動的。每更新一次，就需要給項目成員分發一次新的接口文檔
于是：
A.每改動一次就要新建一份，復制給項目組里很多人，這樣一個文檔復制來復制去，項目組里這么多人，誰都不知道拿到的是不是全新版本 ；
B.改一點就要生成一個新文檔，于是文件夾里的接口文檔可能就是這種形式：
是誰哭了我不說。
這些痛點促成了接口文檔的第一次進化：從word版的接口文檔進化成網頁版的接口文檔。
二、接口文檔的成長體：Markdown
網頁版的接口文檔多完美，只需要分發一個鏈接給項目成員保存起來。
這樣，如果后端修改了接口，直接在網頁里修改，就保證大家看到的都是最新版本的，也不用每次一有改動就發一份新文檔給大家。
這樣一個由markdown生成的靜態的html 頁面，一個接口的關鍵要素全都有
問題解決！
但——
新的問題又產生了。
這個接口文檔是能用了，但又沒那么好用，比如說：
1.寫接口挺麻煩的，完全純手工寫，沒有任何輔助工具，非常花時間
2.接口寫完還不能立刻看到生成的接口文檔的效果，寫錯了還要重新回去調
3.沒有接口規范約束，接口文檔怎么寫，哪些參數要寫，哪些不寫，呈現形式怎么樣全憑開發人員本身的業務水準。
于是就開始了新的一輪的進化——有人開發了一個工具，專門就用來寫接口文檔。
三、接口文檔的完全體：swagger
怎么寫？
在swagger editor里編寫符合swagger 語法的接口文檔，來生成接口文檔，編寫完的接口文檔可以在swagger editor的右側實時預覽：
于是，進化到這個完全體階段的接口文檔工具已經實現了如下功能：
1.網頁版接口文檔支持的在線查看功能，當然他也有，而且這個接口文檔的樣式是符合open api3.0規范的，如果寫得不符合語法，swagger editor 還會報錯來糾正你。
一個標準的接口所應具備的信息：接口方法、接口路徑、請求和響應參數，都能按照固定的格式呈現出來。
2.它還具備了初步、簡單的調試功能，就是接口請求參數為空格，填寫參數、發送請求，就能返回響應參數
好像已經夠用了對不對？
但——等等，這些如果是開發自己一個人用還行，但如果要運用到項目里，那么多的接口文檔，蠻難管理的，swagger editor 不提供項目層級的歸檔和管理，維護也麻煩。
而且，到目前為止，也沒有逃脫接口文檔要靠手寫生成的命運，還要去學swagger 注解，這樣一來，學習成本有了，工作效率也提高不上去。
生成的接口文檔，前端需要使用接口信息來調試頁面，測試會用它來驗證接口。
但目前接口文檔的功能，對前端和測試的工作支持得還不夠呀~
好像....還可以更完美？？！
有痛點就會有解決方案，于是接口文檔開始了新一輪的進化之路，進入究極進化形態的接口文檔工具是——
四、接口文檔的究極進化形態：Apifox
想要團隊協作？安排。
想要不用寫代碼就能生成接口文檔？可以。
想要直接在接口文檔上調試接口？支持。
接口還沒上生產環境、但想要模擬數據可以調試前端頁面？支持。
想要直接用接口數據來做自動化測試？安排。
于是一個究極進化形態的接口文檔工具就誕生了。
首先是在已經存在的接口文檔功能上做優化：
A.可視化的接口設計頁面，不用寫swagger 注解 ，填完參數保存就是一份接口文檔。
只要你懂接口的知識就能上手寫，四舍五入這學習成本就是零。
接口文檔編輯狀態
接口文檔只讀狀態
B.一鍵導出接口文檔，支持只分享部分接口文檔，設置過期時間，設置密碼
C.接口文檔實時更新，
一旦接口文檔發生變更，數據會實時同步到參與項目的所有成員
其次是給前端和測試瘋狂加外掛：
A.接口文檔頁面支持在線調試
分享出去的接口文檔頁面支持簡單的基礎調試功能，如果你如要更加強大的調試輔助，則可以使用Apifox客戶端。
客戶端的調試功能對提取變量、斷言、連接數據庫等功能都做了可視化封裝，不用寫腳本，如果 有復雜的調試需求，仍舊支持腳本調試功能
B.支持生成代碼，
支持的代碼種類也蠻多的，包括前后端常用的各種語言和框架，總共有130多種，javascript和swift，java等等生成的前端代碼復制就能用。
不僅支持生成接口請求代碼，也支持生成數據模型代碼，整個項目的代碼，可以按需生成，然后自己再去做調整，這樣需要寫的代碼量就大大減少了。
C.提供mock環境，
在接口未上線時也能模擬接口請求，構造出高度真實的業務數據供前端測試頁面，后端、測試進行接口的調試和測試
可以復制鏈接到瀏覽器查看生成的在線文檔：
https://www.apifox.cn/apidoc/shared-cbb5c14c-0faa-4b4d-9f6e-7027cd57c702/api-21636796
最后是將接口的一整條工作鏈整合到它這一個工具里：
A.支持項目層次的協作，每個接口歸屬于不同的模塊，分屬到不同的目錄之中。
后端、前端、測試可以使用同一套接口數據源，也就是說接口創建出來之后，后端在上面維護，前端使用他做接口mock，測試用它做接口自動化，數據變更實時同步到各端，不需要切換多個軟件。
B.支持導入postman，swagger等多達20多種格式的接口數據，零成本實現項目遷移
C.支持導出swagger，html，word 格式的接口文檔，也不綁架用戶，你想遷移到其他系統也大大方方成全你。
這樣一套組合拳打下來，基本上你能想到的接口文檔該有的功能它都有了。
官網地址：https://www.apifox.cn/a1javazhiyin
