當前位置:網站首頁>這款阿裏騰訊人都在用的API管理神器,解决你發愁的文檔問題

這款阿裏騰訊人都在用的API管理神器,解决你發愁的文檔問題

2022-05-14 21:59:50Java愛好狂

* 程序員最討厭的兩件事:1. 寫文檔,2. 別人不寫文檔。大多數開發人員不願意寫 API 文檔的原因:寫文檔短期收益遠低於付出的成本,然而並不是所有人都能够堅持做有長期收益的事情的。你因為寫文檔而耽誤了當前項目進度,老板會直接找你麻煩;但是因為沒寫文檔而帶來的長期收益低,老板是看不見的。這就是現實,讓人去做違反人性的事情是非常困難的。 *

作為一個前後端分離模式開發的團隊,我們經常會看到這樣的場景:前端開發和後端開發在一起熱烈的討論“你這接口參數怎麼又變了?”,“接口怎麼又不通了?”,“稍等,我調試下”,“你再試試..."。

那能不能寫好接口文檔,大家都按文檔來開發?很難,因為寫文檔、維護文檔比較麻煩,而且費時,還會經常出現 API 更新了,但文檔還是舊的,各種同步不一致的情况,從而耽擱彼此的時間。

之前我們團隊也遇到了同樣的問題,那麼作為研發團隊的負責人,我是如何帶領團隊解决這個問題的呢?

如何做?

方法其實很簡單,如果能做到讓寫文檔/維護文檔這件事情的短期收益就能遠高於付出的成本,那麼所有問題都能迎刃而解,開發人員就會非常樂意去寫接口文檔。

團隊原來的工作模式

  1. 「API 設計人員」使用 Swagger 寫接口文檔

  2. 「前端開發」 使用 RAP mock 接口數據

  3. 「後端開發」 使用 Postman 調試接口

  4. 「測試人員」 使用 JMeter 測試接口

我們遇到的問題

  1. 我們團隊是前後端同步進入開發的,不能等後端開發完了才出接口文檔,前端再進入開發,所以使用後端代碼注釋自動生成 Swagger 不適合我們。

  2. 寫 Swagger 文檔效率很低,並且有學習門檻,讓團隊所有人都熟練手寫 Swagger 文檔是不現實的,更何况團隊不停有新人進來。

  3. 開發人員在 Swagger 定義好文檔後,接口調試的時候還需要去 Postman 再定義一遍。

  4. 前端開發 Mock 數據的時候又要去 RAP 定義一遍,手動設置好 Mock 規則。

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

  6. 前端根據 RAP Mock 出來的數據開發完,後端根據 Swagger 定義的接口文檔開發完,各自測試測試通過了,本以為可以馬上上線,結果一對接發現各種問題:原來開發過程中接口變更,只修改了 Swagger,但是沒有及時同步修改 RAP。

  7. 同樣,測試在 JMeter 寫好的測試用例,真正運行的時候也會發現各種不一致。

  8. 開發過程,經常會有發現開始定義的接口文檔有不合理的地方,需要臨時調整,經常出現接口改了,但是文檔沒有更新。

  9. 時間久了,各種不一致會越來越嚴重。

如何解决

要做到寫文檔和及時維護文檔的短期收益就能遠高於付出的成本,無非兩個方向:

  1. 降低寫文檔的成本

  2. 增加寫文檔後的收益

鑒於此,我們設想如果有一款工具做到以下這些是不是就非常爽了?

  1. 以完全可視化的界面來編寫文檔,並且是零學習成本,「新人」 一來就能上手。

  2. 可以通過接口文檔定義的數據結構自動 mock出數據,而無需 「前端開發」 再寫mock規則。

  3. 「後端開發」 在接口文檔基礎上調試接口,而無需在去Postman上調試;接口如有變化,調試的時候就自動更新了文檔,零成本的保障了接口維護的及時性。

  4. 「後端開發」 每次調試完一個功能就保存為一個接口用例。

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

  6. 「測試人員」 更加接口文檔自動生成測試用例,然後像JMeter一樣在直接在上面測試。

  7. 根據接口文檔定義的數據結構,自動生成前後端的數據模型代碼。

總結下來,我們需要的就是這麼一款工具:

* 通過一套系統、一份數據,解决多個系統之間的數據同步問題。只要定義好接口文檔,接口調試、數據 Mock、接口測試就可以直接使用,無需再次定義;接口文檔和接口開發調試使用同一個工具,接口調試完成後即可保證和接口文檔定義完全一致。高效、及時、准確! *

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

怎麼辦?自己幹!

於是,我們自己實現了一個Postman + Swagger + RAP + JMeter

這個工具就是 Apifox,經常很長一段時間不斷更新迭代後,我們基本上完全實現了最初的設想,幾乎完美解决了最開始遇到的所有問題,在公司內部大受歡迎。並且也形成了我們自己的最佳實踐。

感興趣的同學可以自己去官網下,別問我為什麼不貼出來,這裏貼不了鏈接,自己懶得去找的同學可以轉發本文+關注+私信【1220】即可獲取我整理的安裝包、相關插件以及使用文檔等(請務必先關注哦,因為現在非好友的消息是收不到的)

最佳實踐

  1. 「前端」(或「後端」)在 「Apifox」 上定好接口文檔初稿。

  2. 「前後端」 一起評審、完善接口文檔,定好接口用例。

  3. 「前端」 使用系統根據接口文檔自動生成的 Mock 數據進入開發。

  4. 「後端」 使用接口用例 調試開發中接口,系統根據接口文檔的定義自動校驗返回的數據是否正確,只要所有接口用例調試通過,接口就開發完成了。

  5. 「後端」 開發完成後,「測試人員」(也可以是「後端」)使用集合測試功能進行多接口集成測試,完整測試整個接口調用流程。

  6. 「前後端」 都開發完,前端從Mock 數據切換到正式數據,聯調通常都會非常順利,因為前後端雙方都完全遵守了接口定義的規範。

對外服務

沒錯,現在我們已經將Apifox產品化對外服務了,你們團隊也可以直接使用Apifox了。

官網:www.apifox.cn

Apifox 解决方案

一、如何解决這些問題

1、Apifox 定比特

Apifox = Postman + Swagger + Mock + JMeter

Apifox 是 API 文檔、API 調試、API Mock、API 自動化測試一體化協作平臺。

通過一套系統、一份數據,解决多個系統之間的數據同步問題。只要定義好接口文檔,接口調試、數據 Mock、接口測試就可以直接使用,無需再次定義;接口文檔和接口開發調試使用同一個工具,接口調試完成後即可保證和接口文檔定義完全一致。高效、及時、准確!

2、Apifox 宗旨

節省研發團隊的每一分鐘!

3、Apifox 功能

  1. 「接口設計」:Apifox 接口文檔遵循 OpenApi 3.0 (原 Swagger)、JSON Schema 規範的同時,提供了非常好用的可視化文檔管理功能,零學習成本,非常高效。並且支持在線分享接口文檔。

  2. 「數據模型」:可複用的數據結構,定義接口返回數據結構及請求參數數據結構(僅 JSON 和 XML 模式)時可直接引用。支持模型直接嵌套引用,直接 JSON/XML 智能導入,支持 oneOf、allOf 等高級組合模式。

  3. 「接口調試」:Postman 有的功能,比如環境變量、前置/後置脚本、Cookie/Session 全局共享 等功能,Apifox 都有,並且比 Postman 更高效好用。接口運行完之後點擊保存為用例按鈕,即可生成接口用例,後續可直接運行接口用例,無需再輸入參數,非常方便。自定義脚本 100% 兼容 Postman 語法,並且支持運行javascript、java、python、php、js、BeanShell、go、shell、ruby、lua等各種語言代碼。

  4. 「接口用例」:通常一個接口會有多種情况用例,比如參數正確用例、參數錯誤用例、數據為空用例、不同數據狀態用例等等。運行接口用例時會自動校驗數據正確性,用接口用例來調試接口非常高效。

  5. 「接口數據 Mock」:內置 Mock.js 規則引擎,非常方便 mock 出各種數據,並且可以在定義數據結構的同時寫好 mock 規則。支持添加“期望”,根據請求參數返回不同 mock 數據。最重要的是 Apifox 零配置 即可 Mock 出非常人性化的數據,具體在本文後面介紹。

  6. 「數據庫操作」:支持讀取數據庫數據,作為接口請求參數使用。支持讀取數據庫數據,用來校驗(斷言)接口請求是否成功。

  7. 「接口自動化測試」:提供接口集合測試,可以通過選擇接口(或接口用例)快速創建測試集。目前接口自動化測試更多功能還在開發中,敬請期待!目標是:JMeter 有的功能基本都會有,並且要更好用。

  8. 「快捷調試」:類似 Postman 的接口調試方式,主要用途為臨時調試一些無需文檔化的接口,無需提前定義接口即可快速調試。

  9. 「代碼生成」:根據接口及數據數據模型定義,系統自動生成接口請求代碼、前端業務代碼及後端業務代碼。

  10. 「團隊協作」:Apifox 天生就是為團隊協作而生的,接口雲端實時同步更新,成熟的團隊/項目/成員權限管理,滿足各類企業的需求。

二、Apifox 做的不僅僅是數據打通

如果你認為 Apifox 只做了數據打通,來提昇研發團隊的效率,那就錯了。Apifox 還做了非常多的創新,來提昇開發人員的效率。

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

通常一個接口會有多種情况用例,比如 正確用例 參數錯誤用例 數據為空用例 不同數據狀態用例。定義接口的時候定義好這些不同狀態的用例,接口調試的時候直接運行,非常高效。

2、“數據模型”定義、引用

可以獨立定義數據模型,接口定義時可以直接引用數據模型,數據模型之間也可以相互引用。同樣的數據結構,只需要定義一次即可多處使用;修改的時候只需要修改一處,多處實時更新,避免不一致。

3、調試時“自動校驗”數據結構

使用 Apifox 調試接口的時候,系統會根據接口文檔裏的定義,自動校驗返回的數據結構是否正確,無需通過肉眼識別,也無需手動寫斷言脚本檢測,非常高效!

​Apifox 自動校驗數據結構

4、“可視化”設置斷言

設置斷言:

​Apifox 設置斷言

運行後,查看斷言結果:

5、“可視化”設置提取變量

6、支持數據庫操作

​7、“零配置”Mock 出非常人性化的數據

先放一張圖對比下 Apifox 和其他同類工具 零配置 mock 出來的數據效果:

​Apifox Mock 數據結果對比同類工具

可以看出 Apifox 零配置 Mock 出來的數據和真實情况是非常接近的,前端開發可以直接使用,而無需再手動寫 mock 規則。

「Apifox 如何做到高效率、零配置生成非常人性化的 mock 數據」

  1. Apifox 根據接口定義裏的數據結構、數據類型,自動生成 mock 規則。

  2. Apifox 內置智能 mock 規則庫,根據字段名、字段數據類型,智能優化自動生成的 mock 規則。如:名稱包含字符串image的string類型字段,自動 mock 出一個圖片地址 URL;包含字符串time的string類型字段,自動 mock 出一個時間字符串;包含字符串city的string類型字段,自動 mock 出一個城市名。

  3. Apifox 根據內置規則,可自動識別出圖片、頭像、用戶名、手機號、網址、日期、時間、時間戳、郵箱、省份、城市、地址、IP 等字段,從而 Mock 出非常人性化的數據。

  4. 除了內置 mock 規則,用戶還可以自定義規則庫,滿足各種個性化需求。支持使用 正則錶達式、通配符 來匹配字段名自定義 mock 規則。

8、生成在線接口文檔

Apifox 項目可“在線分享” API 文檔,分享出去的 API 文檔可設置為公開或需要密碼訪問,非常方便與外部團隊協作。

體驗地址:https://www.apipark.cn/s/ce387612-cfdb-478a-b604-b96d1dbc511b/http/5041285

9、代碼自動生成

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

更重要的是:你可以通過自定義代碼模板來生成符合自己團隊的架構規範的代碼,滿足各種個性化的需求。

10、導入、導出

  1. 支持導出 OpenApi (Swagger)、Markdown、Html 等數據格式,因為可以導出OpenApi格式數據,所以你可以利用 OpenApi (Swagger) 豐富的生態工具完成各種接口相關的事情。

  2. 支持導入 OpenApi (Swagger)、Postman、HAR、RAML、RAP2、YApi、Eolinker、NEI、DOClever、ApiPost 、Apizza 、ShowDoc、API Blueprint、I/O Docs、WADL、Google Discovery等數據格式,方便舊項目遷移。

三、後續功能規劃

  1. 接口文檔公開對外發布。

  2. 接口性能測試支持(類似 JMeter)。

  3. 支持插件市場,可以自己開發插件。

  4. 支持更多接口協議,如GraphQL、websocket等。

  5. 支持離線使用,項目可選擇在線同步(團隊協作)還是僅本地存儲(單機離線使用)。

四、更多 Apifox 功能截圖

​接口調試

版權聲明
本文為[Java愛好狂]所創,轉載請帶上原文鏈接,感謝
https://cht.chowdera.com/2022/134/202205141820529558.html

隨機推薦