接口文檔管理工具-Postman、Swagger、RAP、DOClever

在項目開發測試中，接口文檔是貫穿始終的。先後端開發須要在開發前期進行接口定義並造成文檔，QA在功能測試和接口測試的環節也須要依賴於這些接口文檔進行測試。接口文檔每每以最簡單的靜態文檔的形態存在。然而在緊張的敏捷開發模式下，隨着版本迭代，不少接口發生了變化或者被廢棄，而開發幾乎不會在後期去更新這種靜態文檔。QA人員閱讀「過時」的接口文檔是一件痛苦的事情，與開發的溝通成本不降反升。而這些不便於及時維護的靜態文檔，隨着時間的推移最終無人問津。所以，咱們想要找到一種長期可維護且輕量便捷的接口文檔工具。

Postman

Postman是被你們所熟知的網頁調試Chrome插件，咱們經常用它來進行臨時的http請求調試。幸運的是，Postman能夠將調試過的請求保存到Collection中。造成的Collection就能夠做爲一份簡單有效且支持在線測試的接口文檔，使用同一帳號登陸就能夠作到分享和同步。對QA來講，使用Postman進行接口測試和接口文檔維護是同一件事情，測試即文檔，維護成本也很低。

 

Swagger

「Swagger是一個規範和完整的框架，用於生成、描述、調用和可視化RESTful風格的Web服務。」簡單來講，Swagger是一個功能強大的接口管理工具，而且提供了多種編程語言的先後端分離解決方案。Swagger主要包含了如下4個部分：

1. Swagger能夠直接嵌入項目中，經過開發時編寫註釋，自動生成接口文檔；

2. Swagger包含了Swagger Editor，它是使用yaml語言的Swagger API的編輯器，支持導出yaml和json格式的接口文件；

3. Swagger包含了Swagger UI，它將Swagger Editor編輯好的接口文檔以html的形式展現出來；

4. Swagger支持根據定義的接口導出各類語言的服務端或客戶端代碼。

　　其中1和4是更加面向開發的內容，開發團隊要有自動生成文檔的需求，在開發和自測中遵循先後端分離。而2和3是相對能夠獨立出來的、可供QA人員參考的接口文檔管理方案，也是咱們主要關注的部分。

Swagger提供了Swagger Editor和Swagger UI的在線demo，以下圖。能夠看出，Swagger能夠完整地定義一個接口的內容，包括各個參數、返回值的具體結構、類型，Swagger Editor能夠實時進行編輯並在線調試。編輯好的API能夠導出爲json文件，使用Swagger UI打開便可以看到更美觀的接口文檔。

 

Swagger Editor和SwaggerUI的本地部署十分簡單，這二者均可以直接從Github上下載源碼，將其部署到本地Tomcat服務器上，而後經過瀏覽器訪問便可。官方還提供了其餘幾種部署方式，具體步驟在幫助文檔中有詳細說明，這裏再也不贅述。

RAP

RAP是阿里的一套完整的可視化接口管理工具，能夠定義接口結構，動態生成模擬數據，校驗真實接口正確性。不只如此，RAP圍繞接口定義，提供了一系列包括團隊管理、項目管理、文檔版本管理、mock插件等服務。

有關RAP的使用，RAP官網提供了很是詳細的wiki和視頻教程。與Swagger須要使用標記語言編寫不一樣，RAP能夠徹底可視化地定義項目相關信息，定義接口的請求響應等等，學習成本較低。RAP還爲後端開發人員提供了校驗接口的功能，爲前端開發人員提供了mock數據的工具等。

 

DOClever

 

DOClever是一個可視化接口管理工具 ,能夠分析接口結構，校驗接口正確性， 圍繞接口定義文檔，經過一系列自動化工具提高咱們的協做效率。DOClever先後端所有采用了javascript來做爲開發語言，前端用的是vue+element UI，後端是express+mongodb，這樣的框架集成了高併發，迭代快的特色，保證系統的穩定可靠。

 

DOClever產品功能以下：

 

· 能夠對接口信息進行編輯管理，支持 get,post,put,delete,patch 五種方法，支持 https 和 https 協議，而且支持 query，body，json，raw，rest，formdata 的參數可視化編輯。同時對 json 能夠進行無限層次可視化編輯。而且，狀態碼，代碼注入，markdown 文檔等附加功能應有盡有。

 

· 接口調試運行，能夠對參數進行加密，從 md5 到 aes 包羅萬象，返回參數與模型實時分析對比，給出不一致的地方，找出接口可能出現的問題。若是你不想手寫文檔，那麼試試接口的數據生成功能，能夠對接口運行的數據一鍵生成文檔信息。

 

· mock 的無縫整合，DOClever 本身就是一個 mock 服務器，當你把接口的開發狀態設置成已完成，本地 mock 便會自動請求真實接口數據，不然返回事先定義好的 mock 數據。

 

· 支持 postman，rap，swagger 的導入，方便你作無縫遷移，同時也支持 html 文件的導出，方便你離線瀏覽！

 

· 項目版本和接口快照功能並行，你能夠爲一個項目定義 1.0，1.1，1.2 版本，而且能夠自由的在不一樣版本間切換回滾，不再怕接口信息的遺失，同時接口也有快照功能，當你接口開發到一半或者接口需求變動的時候，能夠隨時查看以前編輯的接口信息。

 

· 自動化測試功能，目前市面上相似平臺的接口自動化測試大部分都是僞自動化，對於一個複雜的場景，好比獲取驗證碼，登錄，獲取訂單列表，獲取某個特定訂單詳情這樣一個上下文關聯的一系列操做無能爲力。而 DOClever 首創的自動化測試功能，只須要你編寫極少許的 javascript 代碼即可以在網頁裏完成這樣一系列操做，同時，DOClever 還提供了後臺定時批量執行測試用例並把結果發送到團隊成員郵箱的功能，你能夠及時獲取接口的運行狀態。

 

· 團隊協做功能，不少相似的平臺這樣的功能是收費的，可是 DOClever 以爲好東西須要共享出來，你能夠新建一個團隊，而且把團隊內的成員都拉進來，給他們分組，給他們分配相關的項目以及權限，發佈團隊公告等等。

 

DOClever 開源免費，支持內網部署，不少公司考慮到數據的安全性，不肯意把接口放到公網上，沒有關係，DOClever 給出一個方便快捷的解決方案，你能夠把平臺放到本身的內網上，徹底不須要鏈接外網，同時功能同樣也很多，即使是對於產品的升級，DOClever 也提供了很便捷的升級方案！

 

官網： http://doclever.cn

Github: https://github.com/sx1989827/DOClever 

碼雲: https://git.oschina.net/sx1989827/SBDoc 

文檔: http://doclever.cn/help/help.html

 QQ 羣：611940610 

總結

Postman是一個測試向的API小工具，能夠很是輕量地維護一份「測試記錄」，適合小的測試團隊本身使用並維護。Swagger豐富且獨立的各個功能使得它能夠被應用在各類需求下，不管是開發仍是測試均可以使用這個工具，來優化本身的開發過程，進行接口文檔維護、接口測試等；但Swagger的學習和接入成本相對較高，須要開發與測試的深刻配合。RAP的應用範圍很是明確，是一個面向開發人員自測和聯調的工具性平臺，它更適合以開發爲核心對接口進行維護，但目前基本不在維護。DOClever是一款功能比較強大的平臺，在國內好評率很高，並且產品徹底免費開源，可線下部署；同時產品更新迭代比較頻繁，能夠看出他們也是在用心作這個產品；

 

以上僅供測試人員參考。