簡直離譜！這才是 21 世紀(jì)的 API 文檔該有的樣子！

哈嘍我是樹醬，今天分享一個超級離譜的神級API文檔。

前后端差點(diǎn)打起來

事情是這樣的：今天我們公司的后端說他接口寫完了，并分享了一個接口文檔給我。用的就是 Swagger UI 自動生成的那種接口文檔，就像這種：

這種 Swagger 文檔我每次看著就頭大，毛病多多：

• 查看多級模型時要一級級點(diǎn)開
• 在接口數(shù)量變多的時候非常難用，連分類菜單都沒有
• 提交參數(shù)為 JSON 的時候不能格式化
• 參數(shù)出錯的時候查找麻煩
• 返回結(jié)果不能折疊，長得沒法看

時間比較緊急，我就按照他給的文檔里的參數(shù)與響應(yīng)數(shù)據(jù)，寫到了我的前端頁面上，前端這邊簡單自測了一下就匆匆上線了。

上線完當(dāng)晚就炸了。。

頁面上各種接口報錯：

• 參數(shù)不存在
• 參數(shù)類型錯誤
• 接口不存在（是因?yàn)榻涌趯戝e了）

老大馬上過來找我倆，但是前后端各執(zhí)一詞：

• 前端：我吊你，怎么你分享的接口這么多錯誤？
• 后端：我吊你，你用之前不會測一測接口正不正常？
• 前端：我為什么要測？你開發(fā)的接口，你自己不測好？
• 后端：我怎么知道你要用什么樣的數(shù)據(jù)！你要是稍微測一下接口，能有這么多事？

歸根結(jié)底是個成本問題

這時候老大很冷靜，阻止了我們的吵架。

老大分析了一下這次事故的主要原因：

• 1、后端馬虎了，一些接口沒有寫對，也忘記調(diào)試了
• 2、時間緊，前端沒來得及完全測接口

然后老大說，這歸根結(jié)底是個成本問題。要是前后端測接口都特別簡單方便，你們這個問題就不存在了嘛！

你們現(xiàn)在用的在線接口文檔，功能幾乎為零。應(yīng)該選一個功能更加強(qiáng)大的在線接口文檔工具，直接在線就把接口調(diào)了，你們是不是就不會出這些問題了。

這個工具應(yīng)該具備以下功能：

• 調(diào)試功能，前端能很方便地調(diào)試接口數(shù)據(jù)
• 代碼生成功能，這樣前端可以少寫點(diǎn)代碼，提高效率同時也提高了準(zhǔn)確性
• 接口同步功能，接口文檔一定要是最新的代碼信息

我們紛紛點(diǎn)頭，是啊是啊。

老大說，我最近試了一款工具，就可以零成本地解決你們這些問題！

然后他給我們看了一個神仙文檔。

就是這個??！??????

為什么說它神仙呢？因?yàn)樗鼭M身都是牛逼到不行的特性，比平常見到那些 API 文檔不知道高到哪里去了。

在線調(diào)試

這個文檔是用?Apifox?做的，我之前有試用過這個工具，完全免費(fèi)不限功能的，沒想到最近又有這么多厲害的新功能出來了。

點(diǎn)擊文檔右上角的運(yùn)行按鈕，就會出現(xiàn)“在線運(yùn)行”的模塊

這個界面上就能直接調(diào)試接口了！直接 1. 填參數(shù)，2. 選環(huán)境，3. 點(diǎn)發(fā)送，接口請求就發(fā)出去了！下面就有返回結(jié)果！根本用不著 Postman！更不用把 API 照著抄一遍！

我心想，如果當(dāng)時上線之前，用的是?Apifox?的話，那簡直是不會出現(xiàn)事故：

• 參數(shù)不存在？我在線調(diào)試后獲得數(shù)據(jù)了，通過比對我知道哪個參數(shù)不存在
• 參數(shù)類型錯誤？同樣的，在線調(diào)試之后，通過比對，我知道哪個參數(shù)的類型是錯的
• 接口不存在（是因?yàn)榻涌趯戝e了）？調(diào)試的時候就報接口不存在了，第一時間找后端~

自動生成

我跟老大說，這個功能看起來是很強(qiáng)大啊?？墒且巧暇€時間緊，誰有功夫去搞這么個接口文檔啊，配置起來應(yīng)該很麻煩吧？

老大邪魅一笑。

他說，這個文檔，是自！動！生！成！的！

只要把 Swagger 的 URL 填到 Apifox 里面去，Apifox 就會自動導(dǎo)入 API 定義，然后就能生成這個好用的文檔！

后端隨便改代碼，前端隨時可以在線調(diào)試！

而且，還可以導(dǎo)入多個來源的 Swagger！一套接口文檔來自多個不同的后端項(xiàng)目也沒問題！

生成請求代碼

后端說，不就是一個在線調(diào)試接口嗎，也沒有到神仙的地步嘛。

老大說，你還是太年輕。

在這個在線文檔頁面上，還有一行熟悉的 icon。這是什么呢？

自！動！生！成！代！碼！

點(diǎn)擊對應(yīng)的語言，就能直接生成請求的代碼?。?？？

我選擇了 JavaScript 之后，居然還提供了 Fetch、Axios、Jquery 等等請求方式的代碼？？？

我直接 copy 一下代碼，粘進(jìn)代碼里就能用？？？

一個在線文檔，卷成這樣至于嘛？？？

生成模型代碼

老大說，別急，還沒完。

API 文檔嘛，都會有個“返回響應(yīng)”的模塊，就是告訴你后端吐出來的數(shù)據(jù)是什么類型什么長度等等。前端再寫個數(shù)據(jù)結(jié)構(gòu)把這些數(shù)據(jù)接著，然后放進(jìn)頁面里去。

在這個神仙文檔里呢，“返回響應(yīng)”里也有個“生成代碼”。

我點(diǎn)了一下，就彈出了這個框：

左邊還可以選擇你生成代碼的配置，包括：編程語言、命名風(fēng)格、校驗(yàn)開啟等等。

我看了看，Java，C，C++，JS，Swift，Go，Python，TypeScript……基本上我知道的語言全都有。

怎么著？返回?cái)?shù)據(jù)結(jié)構(gòu)的代碼也不用寫了？復(fù)制一下粘過去就行了？

我默默翻了翻它自動生成的代碼，又關(guān)上了。

我感覺我自己寫的 Java 代碼還沒它自動生成寫的好。

云端 Mock

我說老大，我明白了。我這就去下載 Apifox，下個迭代我就用這個在線文檔。哦不，下個迭代我就逼后端用這個在線文檔。

老大說，急什么。等我說完。你知道云端 Mock?嗎？

我說，云嘛，神仙都是要駕云的，這很正常。

老大說你正常一點(diǎn)。云端 Mock，就是在 API 文檔頁面上就直接實(shí)現(xiàn) Mock 服務(wù)，虛擬一個服務(wù)端出來。

我：？？？

老大說，比如，我們要請求一個銀行的 API，銀行肯定不會讓你隨便請求啊，都是要驗(yàn)證身份限制次數(shù)的。用這個 Apifox 呢，你就可以直接在接口文檔上請求 Mock 數(shù)據(jù)了，也不會限制你的次數(shù)，也不會收你的錢。

我說老大，咱們是不是跳得有點(diǎn)快。你駕云我跟不上的。

老大說沒有啊，我們不是在聊這個在線文檔的特性嘛。你看，這里有測試環(huán)境、正式環(huán)境和云端 Mock 環(huán)境，你只要切換到云端 Mock 環(huán)境，請求就會發(fā)給 Mock 服務(wù)器了，跟正式環(huán)境調(diào)試一樣一樣的。

我：！?。。?！

還可以這樣？？

老大又用瀏覽器打開了這個 URL（https://mock.apifox.cn/m1/1035644-0-default/users/2），說你看，直接訪問 URL 就能獲取到 Mock 數(shù)據(jù)了，你們前端用起來是不是很爽？

我猛點(diǎn)頭。

這個時候，后端說，那是不是我們直接把常用的那些第三方 API 都做成這種能云端 Mock 的 API 文檔，然后開發(fā)就都能直接調(diào)試第三方接口了？連 Mock 服務(wù)器都不用架？

我：

API Hub

老大說，你們啊，too young too simple，sometimes naive.

給你們看個東西。

這個，叫做 API Hub。

在 Apifox 里面，已經(jīng)把這些最常用的第三方 API 都做好了！即時通訊的，電商的，查快遞的，項(xiàng)目管理的，統(tǒng)統(tǒng)都有！每一個都可以在線運(yùn)行！生成代碼！也可以克隆到自己的項(xiàng)目里，然后用云端 Mock！

老大說，人家都把接口文檔公開出來了，你們也好好學(xué)學(xué)人家大廠的接口是怎么設(shè)計(jì)的。咱們公司有接口要公開出去的話，也可以發(fā)布到這個 API Hub。

老大說，好了，我說完了。你們都聽懂了嗎？

我說，懂了，明天就去跟后端對線。

后端說，等什么明天！我現(xiàn)在就要！

老大說，哦對了，我看他們官方還有預(yù)告，后續(xù)會支持更強(qiáng)大的文檔功能，包括自定義域名、自定義導(dǎo)航、多主題樣式選擇、自定義 css、自定義頁面等等這些，你們都要關(guān)注一下。

Apifox

最后，老大語重心長地說，年輕人啊，還是要多學(xué)學(xué)先進(jìn)技術(shù)和工具。

Apifox = Postman + Swagger + Mock + JMeter。集接口文檔工具、接口 Mock 工具、接口自動化測試工具、接口調(diào)試工具于一體，提升 10 倍研發(fā)效率。

在這些核心功能之外，Apifox 還提供了大量創(chuàng)新的圍繞 API 的擴(kuò)展特性，適合各種規(guī)模的開發(fā)團(tuán)隊(duì)使用。

要是使用過程中有問題的話，還可以加入 Apifox 用戶群提問和學(xué)習(xí)。

趕緊點(diǎn)擊“閱讀原文”去下載吧。http://apifox.cn/a1codertree