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

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

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

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

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

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

如何做？

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

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

1. API 設(shè)計(jì)人員使用 Swagger 寫 API 文檔

2. 前端開發(fā)?使用 mock.js ?mock 假的 API 數(shù)據(jù)

3. 后端開發(fā)?使用 Postman 調(diào)試 API

4. 測試人員?使用 JMeter 測試 API

我們遇到的問題

1. 我們團(tuán)隊(duì)是前后端同步進(jìn)入開發(fā)的，不能等后端開發(fā)完了才出接口文檔，前端再進(jìn)入開發(fā)，所以使用后端代碼注釋自動(dòng)生成 Swagger 不適合我們。

2. 寫 Swagger 文檔效率很低，并且有學(xué)習(xí)門檻，讓團(tuán)隊(duì)所有人都熟練手寫 Swagger 文檔是不現(xiàn)實(shí)的，更何況團(tuán)隊(duì)不停有新人進(jìn)來。

3. 開發(fā)人員在 Swagger 定義好文檔后，接口調(diào)試的時(shí)候還需要去 Postman 再定義一遍。

4. 前端開發(fā) Mock 數(shù)據(jù)的時(shí)候又要去 mock 工具里定義一遍，手動(dòng)設(shè)置好 Mock 規(guī)則。

5. 測試人員需要去 JMeter 定義一遍。

6. 前端根據(jù) mock 工具出來的數(shù)據(jù)開發(fā)完，后端根據(jù) Swagger 定義的接口文檔開發(fā)完，各自測試測試通過了，本以為可以馬上上線，結(jié)果一對接發(fā)現(xiàn)各種問題：原來開發(fā)過程中接口變更，只修改了 Swagger，但是沒有及時(shí)同步修改 mock。

7. 同樣，測試在 JMeter 寫好的測試用例，真正運(yùn)行的時(shí)候也會發(fā)現(xiàn)各種不一致。

8. 開發(fā)過程，經(jīng)常會有發(fā)現(xiàn)開始定義的接口文檔有不合理的地方，需要臨時(shí)調(diào)整，經(jīng)常出現(xiàn)接口改了，但是文檔沒有更新。

9. 時(shí)間久了，各種不一致會越來越嚴(yán)重。

如何解決

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

1. 降低寫文檔的成本

2. 增加寫文檔后的收益

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

1. 以完全可視化的界面來編寫文檔，并且是零學(xué)習(xí)成本，新人?一來就能上手。

2. 可以通過接口文檔定義的數(shù)據(jù)結(jié)構(gòu)自動(dòng) mock出數(shù)據(jù)，而無需?前端開發(fā)?再寫mock規(guī)則，直接開工。

3. 后端開發(fā)?在接口文檔基礎(chǔ)上調(diào)試接口，而無需在去Postman上調(diào)試；接口如有變化，調(diào)試的時(shí)候就自動(dòng)更新了文檔，零成本的保障了接口維護(hù)的及時(shí)性；自動(dòng)根據(jù)文檔校驗(yàn)數(shù)據(jù)結(jié)構(gòu)，無需肉眼校驗(yàn)，無需手動(dòng)寫斷言。

4. 后端開發(fā)?每次調(diào)試完一個(gè)功能就保存為一個(gè)接口用例。

5. 測試人員?直接使用接口用例測試接口。

6. 測試人員?更加接口文檔自動(dòng)生成測試用例，然后像JMeter一樣在直接在上面測試。

7. 根據(jù)接口文檔定義的數(shù)據(jù)結(jié)構(gòu)，自動(dòng)生成前后端的數(shù)據(jù)模型代碼。

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

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

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

怎么辦？自己干！

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

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

最佳實(shí)踐

1. 前端（或后端）在?Apifox?上定好接口文檔初稿。

2. 前后端?一起評審、完善接口文檔，定好接口用例。

3. 前端?使用?Apifox?自動(dòng)生成的?Mock 數(shù)據(jù)進(jìn)入開發(fā)，而無需手寫mock規(guī)則，直接開工。

4. 后端?使用接口用例?調(diào)試開發(fā)中接口，系統(tǒng)根據(jù)接口文檔的定義自動(dòng)校驗(yàn)返回的數(shù)據(jù)是否正確，只要所有接口用例調(diào)試通過，接口就開發(fā)完成了。

5. 后端?開發(fā)完成后，測試人員（也可以是后端）使用集合測試功能進(jìn)行多接口集成測試，完整測試整個(gè)接口調(diào)用流程。

6. 前后端?都開發(fā)完，前端從Mock 數(shù)據(jù)切換到正式數(shù)據(jù)，聯(lián)調(diào)通常都會非常順利，因?yàn)榍昂蠖穗p方都完全遵守了接口定義的規(guī)范。

Apifox 解決方案

一、如何解決這些問題

1、Apifox 定位

Apifox = Postman + Swagger + Mock + JMeter

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

通過一套系統(tǒng)、一份數(shù)據(jù)，解決多個(gè)系統(tǒng)之間的數(shù)據(jù)同步問題。只要定義好接口文檔，接口調(diào)試、數(shù)據(jù) Mock、接口測試就可以直接使用，無需再次定義；接口文檔和接口開發(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)及請求參數(shù)數(shù)據(jù)結(jié)構(gòu)（僅 JSON 和 XML 模式）時(shí)可直接引用。支持模型直接嵌套引用，直接 JSON/XML 智能導(dǎo)入，支持 oneOf、allOf 等高級組合模式。

3. 接口調(diào)試：Postman 有的功能，比如環(huán)境變量、前置/后置腳本、Cookie/Session 全局共享 等功能，Apifox 都有，并且比 Postman 更高效好用。接口運(yùn)行完之后點(diǎn)擊保存為用例按鈕，即可生成接口用例，后續(xù)可直接運(yùn)行接口用例，無需再輸入?yún)?shù)，非常方便。自定義腳本 100% 兼容 Postman 語法，并且支持運(yùn)行javascript、java、python、php、js、BeanShell、go、shell、ruby、lua等各種語言代碼。

4. 接口用例：通常一個(gè)接口會有多種情況用例，比如參數(shù)正確用例、參數(shù)錯(cuò)誤用例、數(shù)據(jù)為空用例、不同數(shù)據(jù)狀態(tài)用例等等。運(yùn)行接口用例時(shí)會自動(dòng)校驗(yàn)數(shù)據(jù)正確性，用接口用例來調(diào)試接口非常高效。

5. 接口數(shù)據(jù) Mock：內(nèi)置 Mock.js 規(guī)則引擎，非常方便 mock 出各種數(shù)據(jù)，并且可以在定義數(shù)據(jù)結(jié)構(gòu)的同時(shí)寫好 mock 規(guī)則。支持添加“期望”，根據(jù)請求參數(shù)返回不同 mock 數(shù)據(jù)。最重要的是 Apifox?零配置?即可 Mock 出非常人性化的數(shù)據(jù)，具體在本文后面介紹。

6. 數(shù)據(jù)庫操作：支持讀取數(shù)據(jù)庫數(shù)據(jù)，作為接口請求參數(shù)使用。支持讀取數(shù)據(jù)庫數(shù)據(jù)，用來校驗(yàn)(斷言)接口請求是否成功。

7. 接口自動(dòng)化測試：提供接口集合測試，可以通過選擇接口（或接口用例）快速創(chuàng)建測試集。目前接口自動(dòng)化測試更多功能還在開發(fā)中，敬請期待！目標(biāo)是：JMeter 有的功能基本都會有，并且要更好用。

8. 快捷調(diào)試：類似 Postman 的接口調(diào)試方式，主要用途為臨時(shí)調(diào)試一些無需文檔化的接口，無需提前定義接口即可快速調(diào)試。

9. 代碼生成：根據(jù)接口及數(shù)據(jù)數(shù)據(jù)模型定義，系統(tǒng)自動(dòng)生成接口請求代碼、前端業(yè)務(wù)代碼及后端業(yè)務(wù)代碼。

10. 團(tuán)隊(duì)協(xié)作：Apifox 天生就是為團(tuán)隊(duì)協(xié)作而生的，接口云端實(shí)時(shí)同步更新，成熟的團(tuán)隊(duì)/項(xiàng)目/成員權(quán)限管理，滿足各類企業(yè)的需求。

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

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

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

通常一個(gè)接口會有多種情況用例，比如?正確用例?參數(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)會根據(jù)接口文檔里的定義，自動(dòng)校驗(yàn)返回的數(shù)據(jù)結(jié)構(gòu)是否正確，無需通過肉眼識別，也無需手動(dòng)寫斷言腳本檢測，非常高效！

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

設(shè)置斷言：

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

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

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

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

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

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

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

1. Apifox 根據(jù)接口定義里的數(shù)據(jù)結(jié)構(gòu)、數(shù)據(jù)類型，自動(dòng)生成 mock 規(guī)則。

2. Apifox 內(nèi)置智能 mock 規(guī)則庫，根據(jù)字段名、字段數(shù)據(jù)類型，智能優(yōu)化自動(dòng)生成的 mock 規(guī)則。如：名稱包含字符串image的string類型字段，自動(dòng) mock 出一個(gè)圖片地址 URL；包含字符串time的string類型字段，自動(dòng) mock 出一個(gè)時(shí)間字符串；包含字符串city的string類型字段，自動(dòng) mock 出一個(gè)城市名。

3. Apifox 根據(jù)內(nèi)置規(guī)則，可自動(dòng)識別出圖片、頭像、用戶名、手機(jī)號、網(wǎng)址、日期、時(shí)間、時(shí)間戳、郵箱、省份、城市、地址、IP 等字段，從而 Mock 出非常人性化的數(shù)據(jù)。

4. 除了內(nèi)置 mock 規(guī)則，用戶還可以自定義規(guī)則庫，滿足各種個(gè)性化需求。支持使用?正則表達(dá)式、通配符?來匹配字段名自定義 mock 規(guī)則。

8、生成在線接口文檔

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

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

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

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

更重要的是：你可以通過自定義代碼模板來生成符合自己團(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. 接口性能測試支持（類似 JMeter）。

3. 支持插件市場，可以自己開發(fā)插件。

4. 開放 Apifox API，允許開發(fā)者通過 API 調(diào)用 Apifox 的功能。

5. 支持更多接口協(xié)議，如GraphQL、gRPC、websocket等。

6. 支持離線使用，項(xiàng)目可選擇在線同步（團(tuán)隊(duì)協(xié)作）還是僅本地存儲（單機(jī)離線使用）。

四、更多 Apifox 功能截圖