還在發(fā)愁寫API文檔？推薦一款阿里騰訊都在用的API管理神器！
前言
?程序員最討厭的兩件事：1. 寫文檔，2. 別人不寫文檔。大多數(shù)開(kāi)發(fā)人員不愿意寫 API 文檔的原因：
?寫文檔短期收益遠(yuǎn)低于付出的成本，然而并不是所有人都能夠堅(jiān)持做有長(zhǎng)期收益的事情的。你因?yàn)閷懳臋n而耽誤了當(dāng)前項(xiàng)目進(jìn)度，老板會(huì)直接找你麻煩；但是因?yàn)闆](méi)寫文檔而帶來(lái)的長(zhǎng)期收益低，老板是看不見(jiàn)的。這就是現(xiàn)實(shí)，讓人去做違反人性的事情是非常困難的。
作為一個(gè)前后端分離模式開(kāi)發(fā)的團(tuán)隊(duì)，我們經(jīng)常會(huì)看到這樣的場(chǎng)景：前端開(kāi)發(fā)和后端開(kāi)發(fā)在一起熱烈的討論“你這接口參數(shù)怎么又變了？”，“接口怎么又不通了？”，“稍等，我調(diào)試下”，“你再試試..."。
那能不能寫好接口文檔，大家都按文檔來(lái)開(kāi)發(fā)？很難，因?yàn)閷懳臋n、維護(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)單，如果能做到讓寫文檔/維護(hù)文檔這件事情的短期收益就能遠(yuǎn)高于付出的成本，那么所有問(wèn)題都能迎刃而解，開(kāi)發(fā)人員就會(huì)非常樂(lè)意去寫接口文檔。
團(tuán)隊(duì)原來(lái)的工作模式
「API 設(shè)計(jì)人員」使用 Swagger 寫接口文檔 「前端開(kāi)發(fā)」?使用 RAP mock 接口數(shù)據(jù) 「后端開(kāi)發(fā)」?使用 Postman 調(diào)試接口 「測(cè)試人員」?使用 JMeter 測(cè)試接口
我們遇到的問(wèn)題
我們團(tuán)隊(duì)是前后端同步進(jìn)入開(kāi)發(fā)的，不能等后端開(kāi)發(fā)完了才出接口文檔，前端再進(jìn)入開(kāi)發(fā)，所以使用后端代碼注釋自動(dòng)生成 Swagger 不適合我們。 寫 Swagger 文檔效率很低，并且有學(xué)習(xí)門檻，讓團(tuán)隊(duì)所有人都熟練手寫 Swagger 文檔是不現(xiàn)實(shí)的，更何況團(tuán)隊(duì)不停有新人進(jìn)來(lái)。 開(kāi)發(fā)人員在 Swagger 定義好文檔后，接口調(diào)試的時(shí)候還需要去 Postman 再定義一遍。 前端開(kāi)發(fā) Mock 數(shù)據(jù)的時(shí)候又要去 RAP 定義一遍，手動(dòng)設(shè)置好 Mock 規(guī)則。 測(cè)試人員需要去 JMeter 定義一遍。 前端根據(jù) RAP 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í)同步修改 RAP。 同樣，測(cè)試在 JMeter 寫好的測(cè)試用例，真正運(yùn)行的時(shí)候也會(huì)發(fā)現(xiàn)各種不一致。 開(kāi)發(fā)過(guò)程，經(jīng)常會(huì)有發(fā)現(xiàn)開(kāi)始定義的接口文檔有不合理的地方，需要臨時(shí)調(diào)整，經(jīng)常出現(xiàn)接口改了，但是文檔沒(méi)有更新。 時(shí)間久了，各種不一致會(huì)越來(lái)越嚴(yán)重。
如何解決
要做到寫文檔和及時(shí)維護(hù)文檔的短期收益就能遠(yuǎn)高于付出的成本，無(wú)非兩個(gè)方向：
降低寫文檔的成本 增加寫文檔后的收益
鑒于此，我們?cè)O(shè)想如果有一款工具做到以下這些是不是就非常爽了？
以 完全可視化的界面來(lái)編寫文檔，并且是零學(xué)習(xí)成本，「新人」?一來(lái)就能上手。可以通過(guò)接口文檔定義的數(shù)據(jù)結(jié)構(gòu) 自動(dòng) mock出數(shù)據(jù)，而無(wú)需?「前端開(kāi)發(fā)」?再寫mock規(guī)則。「后端開(kāi)發(fā)」?在接口文檔基礎(chǔ)上調(diào)試接口，而無(wú)需在去 Postman上調(diào)試；接口如有變化，調(diào)試的時(shí)候就自動(dòng)更新了文檔，零成本的保障了接口維護(hù)的及時(shí)性。「后端開(kāi)發(fā)」?每次調(diào)試完一個(gè)功能就保存為一個(gè) 接口用例。「測(cè)試人員」?直接使用 接口用例測(cè)試接口。「測(cè)試人員」?更加接口文檔自動(dòng)生成測(cè)試用例，然后像 JMeter一樣在直接在上面測(cè)試。根據(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 + RAP + JMeter
這個(gè)工具就是?Apifox，經(jīng)常很長(zhǎng)一段時(shí)間不斷更新迭代后，我們基本上完全實(shí)現(xiàn)了最初的設(shè)想，幾乎完美解決了最開(kāi)始遇到的所有問(wèn)題，在公司內(nèi)部大受歡迎。并且也形成了我們自己的最佳實(shí)踐。
最佳實(shí)踐
「前端」（或「后端」）在?「Apifox」?上定好 接口文檔初稿。「前后端」?一起評(píng)審、完善 接口文檔，定好接口用例。「前端」?使用系統(tǒng)根據(jù)接口文檔自動(dòng)生成的? Mock 數(shù)據(jù)進(jìn)入開(kāi)發(fā)。「后端」?使用 接口用例?調(diào)試開(kāi)發(fā)中接口，系統(tǒng)根據(jù)接口文檔的定義自動(dòng)校驗(yàn)返回的數(shù)據(jù)是否正確，只要所有接口用例調(diào)試通過(guò)，接口就開(kāi)發(fā)完成了。「后端」?開(kāi)發(fā)完成后，「測(cè)試人員」（也可以是「后端」）使用 集合測(cè)試功能進(jìn)行多接口集成測(cè)試，完整測(cè)試整個(gè)接口調(diào)用流程。「前后端」?都開(kāi)發(fā)完，前端從 Mock 數(shù)據(jù)切換到正式數(shù)據(jù)，聯(lián)調(diào)通常都會(huì)非常順利，因?yàn)榍昂蠖穗p方都完全遵守了接口定義的規(guī)范。
對(duì)外服務(wù)
沒(méi)錯(cuò)，現(xiàn)在我們已經(jīng)將Apifox產(chǎn)品化對(duì)外服務(wù)了，你們團(tuán)隊(duì)也可以直接使用Apifox了。
官網(wǎng)：www.apifox.cn
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 功能
「接口設(shè)計(jì)」：Apifox 接口文檔遵循 OpenApi 3.0 (原 Swagger)、JSON Schema 規(guī)范的同時(shí)，提供了非常好用的 可視化文檔管理功能，零學(xué)習(xí)成本，非常高效。并且支持在線分享接口文檔。「數(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í)組合模式。「接口調(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ǔ)言代碼。「接口用例」：通常一個(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)試接口非常高效。「接口數(shù)據(jù) Mock」：內(nèi)置 Mock.js 規(guī)則引擎，非常方便 mock 出各種數(shù)據(jù)，并且可以在定義數(shù)據(jù)結(jié)構(gòu)的同時(shí)寫好 mock 規(guī)則。支持添加“期望”，根據(jù)請(qǐng)求參數(shù)返回不同 mock 數(shù)據(jù)。最重要的是 Apifox 零配置?即可 Mock 出非常人性化的數(shù)據(jù)，具體在本文后面介紹。「數(shù)據(jù)庫(kù)操作」：支持讀取數(shù)據(jù)庫(kù)數(shù)據(jù)，作為接口請(qǐng)求參數(shù)使用。支持讀取數(shù)據(jù)庫(kù)數(shù)據(jù)，用來(lái)校驗(yàn)(斷言)接口請(qǐng)求是否成功。 「接口自動(dòng)化測(cè)試」：提供接口集合測(cè)試，可以通過(guò)選擇接口（或接口用例）快速創(chuàng)建測(cè)試集。目前接口自動(dòng)化測(cè)試更多功能還在開(kāi)發(fā)中，敬請(qǐng)期待！目標(biāo)是：JMeter 有的功能基本都會(huì)有，并且要更好用。 「快捷調(diào)試」：類似 Postman 的接口調(diào)試方式，主要用途為臨時(shí)調(diào)試一些 無(wú)需文檔化的接口，無(wú)需提前定義接口即可快速調(diào)試。「代碼生成」：根據(jù)接口及數(shù)據(jù)數(shù)據(jù)模型定義，系統(tǒng)自動(dòng)生成 接口請(qǐng)求代碼、前端業(yè)務(wù)代碼及后端業(yè)務(wù)代碼。「團(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ù)打通，來(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)寫斷言腳本檢測(cè)，非常高效！
4、“可視化”設(shè)置斷言
設(shè)置斷言：
運(yùn)行后，查看斷言結(jié)果：
5、“可視化”設(shè)置提取變量
6、支持?jǐn)?shù)據(jù)庫(kù)操作
7、“零配置”Mock 出非常人性化的數(shù)據(jù)
先放一張圖對(duì)比下 Apifox 和其他同類工具?零配置?mock 出來(lái)的數(shù)據(jù)效果：
可以看出 Apifox?零配置?Mock 出來(lái)的數(shù)據(jù)和真實(shí)情況是非常接近的，前端開(kāi)發(fā)可以直接使用，而無(wú)需再手動(dòng)寫 mock 規(guī)則。
「Apifox 如何做到高效率、零配置生成非常人性化的 mock 數(shù)據(jù)」
Apifox 根據(jù)接口定義里的數(shù)據(jù)結(jié)構(gòu)、數(shù)據(jù)類型，自動(dòng)生成 mock 規(guī)則。 Apifox 內(nèi)置智能 mock 規(guī)則庫(kù)，根據(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è)城市名。Apifox 根據(jù)內(nèi)置規(guī)則，可自動(dòng)識(shí)別出圖片、頭像、用戶名、手機(jī)號(hào)、網(wǎng)址、日期、時(shí)間、時(shí)間戳、郵箱、省份、城市、地址、IP 等字段，從而 Mock 出非常人性化的數(shù)據(jù)。 除了內(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)出
支持導(dǎo)出? OpenApi (Swagger)、Markdown、Html?等數(shù)據(jù)格式，因?yàn)榭梢詫?dǎo)出OpenApi格式數(shù)據(jù)，所以你可以利用 OpenApi (Swagger) 豐富的生態(tài)工具完成各種接口相關(guān)的事情。支持導(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ī)劃
接口文檔公開(kāi)對(duì)外發(fā)布。 接口性能測(cè)試支持（類似 JMeter）。 支持插件市場(chǎng)，可以自己開(kāi)發(fā)插件。 支持更多接口協(xié)議，如 GraphQL、websocket等。支持離線使用，項(xiàng)目可選擇在線同步（團(tuán)隊(duì)協(xié)作）還是僅本地存儲(chǔ)（單機(jī)離線使用）。
四、更多 Apifox 功能截圖
五、 Apifox 下載地址
請(qǐng)?jiān)L問(wèn) Apifox 官網(wǎng)下載：apifox.cn
?關(guān)注公眾號(hào)：Java后端編程，回復(fù)下面關(guān)鍵字?
要Java學(xué)習(xí)完整路線，回復(fù)??路線?
缺Java入門視頻，回復(fù)：?視頻?
要Java面試經(jīng)驗(yàn)，回復(fù)??面試?
缺Java項(xiàng)目，回復(fù)：?項(xiàng)目?
進(jìn)Java粉絲群：?加群?
PS：如果覺(jué)得我的分享不錯(cuò)，歡迎大家隨手點(diǎn)贊、在看。
（完） 加我"微信"?獲取一份 最新Java面試題資料 請(qǐng)備注：666，不然不通過(guò)～
最近好文
1、Kafka 3.0重磅發(fā)布，棄用 Java 8 的支持！
最近面試BAT，整理一份面試資料《Java面試BAT通關(guān)手冊(cè)》，覆蓋了Java核心技術(shù)、JVM、Java并發(fā)、SSM、微服務(wù)、數(shù)據(jù)庫(kù)、數(shù)據(jù)結(jié)構(gòu)等等。 獲取方式：關(guān)注公眾號(hào)并回復(fù)?java?領(lǐng)取，更多內(nèi)容陸續(xù)奉上。 明天見(jiàn)(??ω??)?