再見(jiàn)丑陋的 Swagger，這個(gè)API神器界面更炫酷，逼格更高，體驗(yàn)更好！

代碼未動(dòng)，文檔先行

其實(shí)大家都知道 API 文檔先行的重要性，但是在實(shí)踐過(guò)程中往往會(huì)遇到很多困難。

程序員最討厭的兩件事：1. 寫(xiě)文檔，2. 別人不寫(xiě)文檔。大多數(shù)開(kāi)發(fā)人員不愿意寫(xiě) API 文檔的原因是寫(xiě)文檔短期收益遠(yuǎn)低于付出的成本，然而并不是所有人都能夠堅(jiān)持做有長(zhǎng)期收益的事情的。

作為一個(gè)前后端分離模式開(kāi)發(fā)的團(tuán)隊(duì)，我們經(jīng)常會(huì)看到這樣的場(chǎng)景：前端開(kāi)發(fā)和后端開(kāi)發(fā)在一起熱烈的討論“你這接口參數(shù)怎么又變了？”，“接口怎么又不通了？”，“稍等，我調(diào)試下”，“你再試試..."。

那能不能寫(xiě)好 API 文檔，大家都按文檔來(lái)開(kāi)發(fā)？很難，因?yàn)閷?xiě)文檔、維護(hù)文檔比較麻煩，而且費(fèi)時(shí)，還會(huì)經(jīng)常出現(xiàn) API 更新了，但文檔還是舊的，各種同步不一致的情況，從而耽擱彼此的時(shí)間。

之前我們團(tuán)隊(duì)也遇到了同樣的問(wèn)題，那么作為研發(fā)團(tuán)隊(duì)的負(fù)責(zé)人，我是如何帶領(lǐng)團(tuán)隊(duì)解決這個(gè)問(wèn)題的呢？

如何做？

方法其實(shí)很簡(jiǎn)單，如果能做到讓寫(xiě)文檔/維護(hù)文檔這件事情的短期收益就能遠(yuǎn)高于付出的成本，那么所有問(wèn)題都能迎刃而解，開(kāi)發(fā)人員就會(huì)非常樂(lè)意去寫(xiě)接口文檔。

團(tuán)隊(duì)原來(lái)的工作模式

1. API 設(shè)計(jì)人員使用 Swagger 寫(xiě) API 文檔
2. 前端開(kāi)發(fā) 使用 mock.js mock 假的 API 數(shù)據(jù)
3. 后端開(kāi)發(fā) 使用 Postman 調(diào)試 API
4. 測(cè)試人員 使用 JMeter 測(cè)試 API

我們遇到的問(wèn)題

1. 我們團(tuán)隊(duì)是前后端同步進(jìn)入開(kāi)發(fā)的，不能等后端開(kāi)發(fā)完了才出接口文檔，前端再進(jìn)入開(kāi)發(fā)，所以使用后端代碼注釋自動(dòng)生成 Swagger 不適合我們。
2. 寫(xiě) Swagger 文檔效率很低，并且有學(xué)習(xí)門(mén)檻，讓團(tuán)隊(duì)所有人都熟練手寫(xiě) Swagger 文檔是不現(xiàn)實(shí)的，更何況團(tuán)隊(duì)不停有新人進(jìn)來(lái)。
3. 開(kāi)發(fā)人員在 Swagger 定義好文檔后，接口調(diào)試的時(shí)候還需要去 Postman 再定義一遍。
4. 前端開(kāi)發(fā) Mock 數(shù)據(jù)的時(shí)候又要去 mock 工具里定義一遍，手動(dòng)設(shè)置好 Mock 規(guī)則。
5. 測(cè)試人員需要去 JMeter 定義一遍。
6. 前端根據(jù) mock 工具出來(lái)的數(shù)據(jù)開(kāi)發(fā)完，后端根據(jù) Swagger 定義的接口文檔開(kāi)發(fā)完，各自測(cè)試測(cè)試通過(guò)了，本以為可以馬上上線，結(jié)果一對(duì)接發(fā)現(xiàn)各種問(wèn)題：原來(lái)開(kāi)發(fā)過(guò)程中接口變更，只修改了 Swagger，但是沒(méi)有及時(shí)同步修改 mock。
7. 同樣，測(cè)試在 JMeter 寫(xiě)好的測(cè)試用例，真正運(yùn)行的時(shí)候也會(huì)發(fā)現(xiàn)各種不一致。
8. 開(kāi)發(fā)過(guò)程，經(jīng)常會(huì)有發(fā)現(xiàn)開(kāi)始定義的接口文檔有不合理的地方，需要臨時(shí)調(diào)整，經(jīng)常出現(xiàn)接口改了，但是文檔沒(méi)有更新。
9. 時(shí)間久了，各種不一致會(huì)越來(lái)越嚴(yán)重。

如何解決

要做到寫(xiě)文檔和及時(shí)維護(hù)文檔的短期收益就能遠(yuǎn)高于付出的成本，無(wú)非兩個(gè)方向：

1. 降低寫(xiě)文檔的成本
2. 增加寫(xiě)文檔后的收益

鑒于此，我們?cè)O(shè)想如果有一款工具做到以下這些是不是就非常爽了？

1. 以完全可視化的界面來(lái)編寫(xiě)文檔，并且是零學(xué)習(xí)成本，新人 一來(lái)就能上手。
2. 可以通過(guò)接口文檔定義的數(shù)據(jù)結(jié)構(gòu)自動(dòng) mock出數(shù)據(jù)，而無(wú)需 前端開(kāi)發(fā) 再寫(xiě)mock規(guī)則，直接開(kāi)工。
3. 后端開(kāi)發(fā) 在接口文檔基礎(chǔ)上調(diào)試接口，而無(wú)需在去Postman上調(diào)試；接口如有變化，調(diào)試的時(shí)候就自動(dòng)更新了文檔，零成本的保障了接口維護(hù)的及時(shí)性；自動(dòng)根據(jù)文檔校驗(yàn)數(shù)據(jù)結(jié)構(gòu)，無(wú)需肉眼校驗(yàn)，無(wú)需手動(dòng)寫(xiě)斷言。
4. 后端開(kāi)發(fā) 每次調(diào)試完一個(gè)功能就保存為一個(gè)接口用例。
5. 測(cè)試人員 直接使用接口用例測(cè)試接口。
6. 測(cè)試人員 更加接口文檔自動(dòng)生成測(cè)試用例，然后像JMeter一樣在直接在上面測(cè)試。
7. 根據(jù)接口文檔定義的數(shù)據(jù)結(jié)構(gòu)，自動(dòng)生成前后端的數(shù)據(jù)模型代碼。

總結(jié)下來(lái)，我們需要的就是這么一款工具：

通過(guò)一套系統(tǒng)、一份數(shù)據(jù)，解決多個(gè)系統(tǒng)之間的數(shù)據(jù)同步問(wèn)題。只要定義好接口文檔，接口調(diào)試、數(shù)據(jù) Mock、接口測(cè)試就可以直接使用，無(wú)需再次定義；接口文檔和接口開(kāi)發(fā)調(diào)試使用同一個(gè)工具，接口調(diào)試完成后即可保證和接口文檔定義完全一致。高效、及時(shí)、準(zhǔn)確！

為此，我們幾乎嘗遍了市面上所有相關(guān)的工具，但是很遺憾，沒(méi)有找到合適的。

怎么辦？自己干！

于是，我們自己實(shí)現(xiàn)了一個(gè)Postman + Swagger + Mock + JMeter

這個(gè)工具就是 Apifox，經(jīng)常很長(zhǎng)一段時(shí)間不斷更新迭代后，我們基本上完全實(shí)現(xiàn)了最初的設(shè)想，幾乎完美解決了最開(kāi)始遇到的所有問(wèn)題，在公司內(nèi)部大受歡迎。并且也形成了我們自己的最佳實(shí)踐。

最佳實(shí)踐

1. 前端（或后端）在 Apifox 上定好接口文檔初稿。
2. 前后端 一起評(píng)審、完善接口文檔，定好接口用例。
3. 前端 使用 Apifox 自動(dòng)生成的 Mock 數(shù)據(jù)進(jìn)入開(kāi)發(fā)，而無(wú)需手寫(xiě)mock規(guī)則，直接開(kāi)工。
4. 后端 使用接口用例 調(diào)試開(kāi)發(fā)中接口，系統(tǒng)根據(jù)接口文檔的定義自動(dòng)校驗(yàn)返回的數(shù)據(jù)是否正確，只要所有接口用例調(diào)試通過(guò)，接口就開(kāi)發(fā)完成了。
5. 后端 開(kāi)發(fā)完成后，測(cè)試人員（也可以是后端）使用集合測(cè)試功能進(jìn)行多接口集成測(cè)試，完整測(cè)試整個(gè)接口調(diào)用流程。
6. 前后端 都開(kāi)發(fā)完，前端從Mock 數(shù)據(jù)切換到正式數(shù)據(jù)，聯(lián)調(diào)通常都會(huì)非常順利，因?yàn)榍昂蠖穗p方都完全遵守了接口定義的規(guī)范。

Apifox 解決方案

一、如何解決這些問(wèn)題

1、Apifox 定位

Apifox = Postman + Swagger + Mock + JMeter

Apifox 是 API 文檔、API 調(diào)試、API Mock、API 自動(dòng)化測(cè)試一體化協(xié)作平臺(tái)。

通過(guò)一套系統(tǒng)、一份數(shù)據(jù)，解決多個(gè)系統(tǒng)之間的數(shù)據(jù)同步問(wèn)題。只要定義好接口文檔，接口調(diào)試、數(shù)據(jù) Mock、接口測(cè)試就可以直接使用，無(wú)需再次定義；接口文檔和接口開(kāi)發(fā)調(diào)試使用同一個(gè)工具，接口調(diào)試完成后即可保證和接口文檔定義完全一致。高效、及時(shí)、準(zhǔn)確！

2、Apifox 宗旨

節(jié)省研發(fā)團(tuán)隊(duì)的每一分鐘！

3、Apifox 功能

1. 接口設(shè)計(jì)：Apifox 接口文檔遵循 OpenApi 3.0 (原 Swagger)、JSON Schema 規(guī)范的同時(shí)，提供了非常好用的可視化文檔管理功能，零學(xué)習(xí)成本，非常高效。并且支持在線分享接口文檔。
2. 數(shù)據(jù)模型：可復(fù)用的數(shù)據(jù)結(jié)構(gòu)，定義接口返回?cái)?shù)據(jù)結(jié)構(gòu)及請(qǐng)求參數(shù)數(shù)據(jù)結(jié)構(gòu)（僅 JSON 和 XML 模式）時(shí)可直接引用。支持模型直接嵌套引用，直接 JSON/XML 智能導(dǎo)入，支持 oneOf、allOf 等高級(jí)組合模式。
3. 接口調(diào)試：Postman 有的功能，比如環(huán)境變量、前置/后置腳本、Cookie/Session 全局共享 等功能，Apifox 都有，并且比 Postman 更高效好用。接口運(yùn)行完之后點(diǎn)擊保存為用例按鈕，即可生成接口用例，后續(xù)可直接運(yùn)行接口用例，無(wú)需再輸入?yún)?shù)，非常方便。自定義腳本 100% 兼容 Postman 語(yǔ)法，并且支持運(yùn)行 javascript、java、python、php、js、BeanShell、go、shell、ruby、lua 等各種語(yǔ)言代碼。
4. 接口用例：通常一個(gè)接口會(huì)有多種情況用例，比如參數(shù)正確用例、參數(shù)錯(cuò)誤用例、數(shù)據(jù)為空用例、不同數(shù)據(jù)狀態(tài)用例等等。運(yùn)行接口用例時(shí)會(huì)自動(dòng)校驗(yàn)數(shù)據(jù)正確性，用接口用例來(lái)調(diào)試接口非常高效。
5. 接口數(shù)據(jù) Mock：內(nèi)置 Mock.js 規(guī)則引擎，非常方便 mock 出各種數(shù)據(jù)，并且可以在定義數(shù)據(jù)結(jié)構(gòu)的同時(shí)寫(xiě)好 mock 規(guī)則。支持添加“期望”，根據(jù)請(qǐng)求參數(shù)返回不同 mock 數(shù)據(jù)。最重要的是 Apifox 零配置 即可 Mock 出非常人性化的數(shù)據(jù)，具體在本文后面介紹。
6. 數(shù)據(jù)庫(kù)操作：支持讀取數(shù)據(jù)庫(kù)數(shù)據(jù)，作為接口請(qǐng)求參數(shù)使用。支持讀取數(shù)據(jù)庫(kù)數(shù)據(jù)，用來(lái)校驗(yàn)(斷言)接口請(qǐng)求是否成功。
7. 接口自動(dòng)化測(cè)試：提供接口集合測(cè)試，可以通過(guò)選擇接口（或接口用例）快速創(chuàng)建測(cè)試集。目前接口自動(dòng)化測(cè)試更多功能還在開(kāi)發(fā)中，敬請(qǐng)期待！目標(biāo)是：JMeter 有的功能基本都會(huì)有，并且要更好用。
8. 快捷調(diào)試：類(lèi)似 Postman 的接口調(diào)試方式，主要用途為臨時(shí)調(diào)試一些無(wú)需文檔化的接口，無(wú)需提前定義接口即可快速調(diào)試。
9. 代碼生成：根據(jù)接口及數(shù)據(jù)數(shù)據(jù)模型定義，系統(tǒng)自動(dòng)生成接口請(qǐng)求代碼、前端業(yè)務(wù)代碼及后端業(yè)務(wù)代碼。
10. 團(tuán)隊(duì)協(xié)作：Apifox 天生就是為團(tuán)隊(duì)協(xié)作而生的，接口云端實(shí)時(shí)同步更新，成熟的團(tuán)隊(duì)/項(xiàng)目/成員權(quán)限管理，滿足各類(lèi)企業(yè)的需求。

二、Apifox 做的不僅僅是數(shù)據(jù)打通

如果你認(rèn)為 Apifox 只做了數(shù)據(jù)打通，來(lái)提升研發(fā)團(tuán)隊(duì)的效率，那就錯(cuò)了。Apifox 還做了非常多的創(chuàng)新，來(lái)提升開(kāi)發(fā)人員的效率。

1、接口支持“用例管理”

通常一個(gè)接口會(huì)有多種情況用例，比如 正確用例 參數(shù)錯(cuò)誤用例 數(shù)據(jù)為空用例 不同數(shù)據(jù)狀態(tài)用例。定義接口的時(shí)候定義好這些不同狀態(tài)的用例，接口調(diào)試的時(shí)候直接運(yùn)行，非常高效。

2、“數(shù)據(jù)模型”定義、引用

可以獨(dú)立定義數(shù)據(jù)模型，接口定義時(shí)可以直接引用數(shù)據(jù)模型，數(shù)據(jù)模型之間也可以相互引用。同樣的數(shù)據(jù)結(jié)構(gòu)，只需要定義一次即可多處使用；修改的時(shí)候只需要修改一處，多處實(shí)時(shí)更新，避免不一致。

3、調(diào)試時(shí)“自動(dòng)校驗(yàn)”數(shù)據(jù)結(jié)構(gòu)

使用 Apifox 調(diào)試接口的時(shí)候，系統(tǒng)會(huì)根據(jù)接口文檔里的定義，自動(dòng)校驗(yàn)返回的數(shù)據(jù)結(jié)構(gòu)是否正確，無(wú)需通過(guò)肉眼識(shí)別，也無(wú)需手動(dòng)寫(xiě)斷言腳本檢測(cè)，非常高效！

4、“可視化”設(shè)置斷言

設(shè)置斷言：

運(yùn)行后，查看斷言結(jié)果：

5、“可視化”設(shè)置提取變量

6、支持?jǐn)?shù)據(jù)庫(kù)操作

7、“零配置”Mock 出非常人性化的數(shù)據(jù)

先放一張圖對(duì)比下 Apifox 和其他同類(lèi)工具 零配置 mock 出來(lái)的數(shù)據(jù)效果：

可以看出 Apifox 零配置 Mock 出來(lái)的數(shù)據(jù)和真實(shí)情況是非常接近的，前端開(kāi)發(fā)可以直接使用，而無(wú)需再手動(dòng)寫(xiě) mock 規(guī)則。

Apifox 如何做到高效率、零配置生成非常人性化的 mock 數(shù)據(jù)

1. Apifox 根據(jù)接口定義里的數(shù)據(jù)結(jié)構(gòu)、數(shù)據(jù)類(lèi)型，自動(dòng)生成 mock 規(guī)則。
2. Apifox 內(nèi)置智能 mock 規(guī)則庫(kù)，根據(jù)字段名、字段數(shù)據(jù)類(lèi)型，智能優(yōu)化自動(dòng)生成的 mock 規(guī)則。如：名稱(chēng)包含字符串image的string類(lèi)型字段，自動(dòng) mock 出一個(gè)圖片地址 URL；包含字符串time的string類(lèi)型字段，自動(dòng) mock 出一個(gè)時(shí)間字符串；包含字符串city的string類(lèi)型字段，自動(dòng) mock 出一個(gè)城市名。
3. Apifox 根據(jù)內(nèi)置規(guī)則，可自動(dòng)識(shí)別出圖片、頭像、用戶名、手機(jī)號(hào)、網(wǎng)址、日期、時(shí)間、時(shí)間戳、郵箱、省份、城市、地址、IP 等字段，從而 Mock 出非常人性化的數(shù)據(jù)。
4. 除了內(nèi)置 mock 規(guī)則，用戶還可以自定義規(guī)則庫(kù)，滿足各種個(gè)性化需求。支持使用 正則表達(dá)式、通配符 來(lái)匹配字段名自定義 mock 規(guī)則。

8、生成在線接口文檔

Apifox 項(xiàng)目可“在線分享” API 文檔，分享出去的 API 文檔可設(shè)置為公開(kāi)或需要密碼訪問(wèn)，非常方便與外部團(tuán)隊(duì)協(xié)作。

體驗(yàn)地址：https://www.apipark.cn/s/ce387612-cfdb-478a-b604-b96d1dbc511b/http/5041285

9、代碼自動(dòng)生成

根據(jù)接口模型定義，自動(dòng)生成各種語(yǔ)言/框架（如 TypeScript、Java、Go、Swift、ObjectiveC、Kotlin、Dart、C++、C#、Rust 等）的業(yè)務(wù)代碼（如 Model、Controller、單元測(cè)試代碼等）和接口請(qǐng)求代碼。目前 Apifox 支持 130 種語(yǔ)言及框架的代碼自動(dòng)生成。

更重要的是：你可以通過(guò)自定義代碼模板來(lái)生成符合自己團(tuán)隊(duì)的架構(gòu)規(guī)范的代碼，滿足各種個(gè)性化的需求。

10、導(dǎo)入、導(dǎo)出

1. 支持導(dǎo)出 OpenApi (Swagger)、Markdown、Html 等數(shù)據(jù)格式，因?yàn)榭梢詫?dǎo)出OpenApi格式數(shù)據(jù)，所以你可以利用 OpenApi (Swagger) 豐富的生態(tài)工具完成各種接口相關(guān)的事情。
2. 支持導(dǎo)入 OpenApi (Swagger)、Postman、HAR、RAML、RAP2、YApi、Eolinker、NEI、DOClever、ApiPost 、Apizza 、ShowDoc、API Blueprint、I/O Docs、WADL、Google Discovery等數(shù)據(jù)格式，方便舊項(xiàng)目遷移。

三、后續(xù)功能規(guī)劃

1. 發(fā)布 Apifox WEB 版，支持在瀏覽器端使用 Apifox。
2. 接口性能測(cè)試支持（類(lèi)似 JMeter）。
3. 支持插件市場(chǎng)，可以自己開(kāi)發(fā)插件。
4. 開(kāi)放 Apifox API，允許開(kāi)發(fā)者通過(guò) API 調(diào)用 Apifox 的功能。
5. 支持更多接口協(xié)議，如GraphQL、gRPC、websocket等。
6. 支持離線使用，項(xiàng)目可選擇在線同步（團(tuán)隊(duì)協(xié)作）還是僅本地存儲(chǔ)（單機(jī)離線使用）。

四、更多 Apifox 功能截圖

五、 Apifox 交流群

掃二維碼進(jìn)微信群，各種使用過(guò)程中的疑問(wèn)，官方工作人員貼心為你解答：

六、 Apifox 下載地址

軟件完全免費(fèi)，復(fù)制下面的鏈接，粘貼到瀏覽器打開(kāi)即可下載，或者點(diǎn)擊閱讀原文直達(dá)！官網(wǎng)地址：https://www.apifox.cn/?utm_source=javaguide