前言

在項(xiàng)目開(kāi)發(fā)測(cè)試中，接口文檔是貫穿始終的。前后端開(kāi)發(fā)需要在開(kāi)發(fā)前期進(jìn)行接口定義并形成文檔，QA在功能測(cè)試和接口測(cè)試的環(huán)節(jié)也需要依賴(lài)于這些接口文檔進(jìn)行測(cè)試。接口文檔往往以最簡(jiǎn)單的靜態(tài)文檔的形態(tài)存在。然而在緊張的敏捷開(kāi)發(fā)模式下，隨著版本迭代，很多接口發(fā)生了變化或者被廢棄，而開(kāi)發(fā)幾乎不會(huì)在后期去更新這種靜態(tài)文檔。QA人員閱讀“過(guò)期”的接口文檔是一件痛苦的事情，與開(kāi)發(fā)的溝通成本不降反升。而這些不便于及時(shí)維護(hù)的靜態(tài)文檔，隨著時(shí)間的推移最終無(wú)人問(wèn)津。因此，我們想要找到一種長(zhǎng)期可維護(hù)且輕量便捷的接口文檔工具。

什么是接口文檔管理工具？

接口文檔管理工具是一個(gè)在線(xiàn)API文檔系統(tǒng)，致力于快速解決團(tuán)隊(duì)內(nèi)部接口文檔的編寫(xiě)，和減少團(tuán)隊(duì)協(xié)作開(kāi)發(fā)的溝通成本。

接口管理工具推薦

作為一個(gè)后端程序員，和前端對(duì)接時(shí)總是需要寫(xiě)冗雜繁瑣的接口文檔，不僅效率低且溝通成本也高， 找到一款能夠提高對(duì)接效率，錄入接口信息的工具是非常有必要的。下面我將推薦幾個(gè)文檔管理工具并進(jìn)行詳細(xì)介紹。

1、目前國(guó)內(nèi)做得比較好的是eoLinker（ eoLinker一直比較低調(diào)，更加專(zhuān)注用戶(hù)體驗(yàn)和功能性的提升。eoLinker有線(xiàn)上版本和開(kāi)源版本，基于PHP。簡(jiǎn)約的設(shè)計(jì)風(fēng)格，這款產(chǎn)品的功能強(qiáng)大，幾乎滿(mǎn)足了程序員的開(kāi)發(fā)需求。（下面是關(guān)于eoLinker詳細(xì)介紹）

附上eoLinker-AMS接口管理系統(tǒng)的一些簡(jiǎn)介（來(lái)自eoLinker的官網(wǎng)）：

注冊(cè)登錄后，其功能一目了然，很容易上手

項(xiàng)目信息頁(yè)面：

其基礎(chǔ)信息一目了然，創(chuàng)建時(shí)間、接口數(shù)量、協(xié)作人數(shù)其我比較關(guān)心的信息都在這里，讓我可以很直觀(guān)了解項(xiàng)目的情況。其中讓我眼前一亮的是可以管理狀態(tài)碼，還可以導(dǎo)入導(dǎo)出項(xiàng)目，這樣線(xiàn)上項(xiàng)目可以導(dǎo)出到本地，極大方便了用戶(hù)操作，不需要煩瑣的操作就可以讓本地及線(xiàn)上項(xiàng)目接口信息保持同步。

接口列表頁(yè)面：

新增接口信息頁(yè)面：

其所添加的信息粒度較小，接口信息直觀(guān)簡(jiǎn)潔，極大提高了開(kāi)發(fā)效率，可以減少成員間的溝通成本。

編輯后接口信息頁(yè)面：

編輯完接口文檔后可直接點(diǎn)擊測(cè)試：（用登陸接口進(jìn)行測(cè)試）

其測(cè)試效果與Postman、DHC等工具并無(wú)過(guò)大差別，文檔寫(xiě)完一鍵測(cè)試，類(lèi)似流水線(xiàn)工作，可以不必像過(guò)去一樣將文檔中信息復(fù)制粘貼到測(cè)試工具上，簡(jiǎn)化了用戶(hù)的操作。不僅如此，它還有mock測(cè)試，生成mock數(shù)據(jù)進(jìn)行測(cè)試。

另外，我們還可以一鍵添加環(huán)境，在往后的測(cè)試中可直接添加測(cè)試環(huán)境要求，簡(jiǎn)化了測(cè)試操作：

接口管理

· 無(wú)論是個(gè)人開(kāi)發(fā)者、創(chuàng)業(yè)團(tuán)隊(duì)還是成熟企業(yè)，eoLinker-AMS接口管理系統(tǒng)都可以滿(mǎn)足對(duì)應(yīng)的接口管理需求。

· 不再需要為每個(gè)項(xiàng)目搭建獨(dú)立的接口管理平臺(tái)和編寫(xiě)離線(xiàn)的接口文檔，一切的項(xiàng)目接口管理都將在云端進(jìn)行。

項(xiàng)目協(xié)作

· 傳統(tǒng)的word、excel以及自建wiki等文檔工具，均無(wú)法擺脫編寫(xiě)繁瑣、閱讀困難、維護(hù)麻煩等缺點(diǎn)。

· eoLinker-AMS接口管理系統(tǒng)能夠讓你注冊(cè)后便開(kāi)始協(xié)作，其規(guī)范化的文檔、清晰的分類(lèi)以及友好的閱讀界面，讓文檔更新和協(xié)作不再痛苦。

在線(xiàn)測(cè)試

· 傳統(tǒng)如DHC以及postman等測(cè)試工具已無(wú)法滿(mǎn)足接口管理工作，并且無(wú)法提供性能測(cè)試報(bào)告。

· eoLinker則將代替?zhèn)鹘y(tǒng)測(cè)試工具，無(wú)須***和安裝，只需網(wǎng)頁(yè)輕輕一點(diǎn)即可得知完整的接口測(cè)試信息。

eoLinker開(kāi)源版本：

eoLinker開(kāi)源版本，其是線(xiàn)上版的精簡(jiǎn)版本，可以讓用戶(hù)部署到自己的服務(wù)器中進(jìn)行操作，部分用戶(hù)希望讓數(shù)據(jù)保存在本地服務(wù)器中，可以用其開(kāi)源版。但如果涉及到更多功能的操作，建議使用其線(xiàn)上版本。

線(xiàn)上版本功能強(qiáng)大，基本對(duì)于接口管理的各種要求都能夠滿(mǎn)足，對(duì)歷史記錄的查看、在線(xiàn)測(cè)試、團(tuán)隊(duì)協(xié)作、接口文檔編寫(xiě)、狀態(tài)碼管理、一些用戶(hù)可用到的小工具皆可在官網(wǎng)找到并正常使用，功能過(guò)多難以全部列出來(lái)，你可以自己進(jìn)入eolinker官網(wǎng)進(jìn)行實(shí)際操作，功能足以滿(mǎn)足你的需求。

2、Postman

Postman是被大家所熟知的網(wǎng)頁(yè)調(diào)試Chrome插件，我們常常用它來(lái)進(jìn)行臨時(shí)的http請(qǐng)求調(diào)試。幸運(yùn)的是，Postman可以將調(diào)試過(guò)的請(qǐng)求保存到Collection中。形成的Collection就可以作為一份簡(jiǎn)單有效且支持在線(xiàn)測(cè)試的接口文檔，使用同一賬號(hào)登錄就可以做到分享和同步。對(duì)QA來(lái)說(shuō)，使用Postman進(jìn)行接口測(cè)試和接口文檔維護(hù)是同一件事情，測(cè)試即文檔，維護(hù)成本也很低。

3、國(guó)外的Swagger

“Swagger是一個(gè)規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化RESTful風(fēng)格的Web服務(wù)。”簡(jiǎn)單來(lái)說(shuō)，Swagger是一個(gè)功能強(qiáng)大的接口管理工具，并且提供了多種編程語(yǔ)言的前后端分離解決方案。Swagger主要包含了以下4個(gè)部分：

1. Swagger可以直接嵌入項(xiàng)目中，通過(guò)開(kāi)發(fā)時(shí)編寫(xiě)注釋?zhuān)詣?dòng)生成接口文檔；

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

3. Swagger包含了Swagger UI，它將Swagger Editor編輯好的接口文檔以html的形式展示出來(lái)；

4. Swagger支持根據(jù)定義的接口導(dǎo)出各種語(yǔ)言的服務(wù)端或客戶(hù)端代碼。

其中1和4是更加面向開(kāi)發(fā)的內(nèi)容，開(kāi)發(fā)團(tuán)隊(duì)要有自動(dòng)生成文檔的需求，在開(kāi)發(fā)和自測(cè)中遵循前后端分離。而2和3是相對(duì)可以獨(dú)立出來(lái)的、可供QA人員參考的接口文檔管理方案，也是我們主要關(guān)注的部分。

Swagger提供了Swagger Editor和Swagger UI的在線(xiàn)demo，如下圖?？梢钥闯觯琒wagger可以完整地定義一個(gè)接口的內(nèi)容，包括各個(gè)參數(shù)、返回值的具體結(jié)構(gòu)、類(lèi)型，Swagger Editor可以實(shí)時(shí)進(jìn)行編輯并在線(xiàn)調(diào)試。編輯好的API可以導(dǎo)出為json文件，使用Swagger UI打開(kāi)即可以看到更美觀(guān)的接口文檔。

Swagger Editor和SwaggerUI的本地部署十分簡(jiǎn)單，這兩者都可以直接從Github上下載源碼，將其部署到本地Tomcat服務(wù)器上，然后通過(guò)瀏覽器訪(fǎng)問(wèn)即可。官方還提供了其他幾種部署方式，具體步驟在幫助文檔中有詳細(xì)說(shuō)明，這里不再贅述。

4、RAP

RAP是阿里的一套完整的可視化接口管理工具，可以定義接口結(jié)構(gòu)，動(dòng)態(tài)生成模擬數(shù)據(jù)，校驗(yàn)真實(shí)接口正確性。不僅如此，RAP圍繞接口定義，提供了一系列包括團(tuán)隊(duì)管理、項(xiàng)目管理、文檔版本管理、mock插件等服務(wù)。

有關(guān)RAP的使用，RAP官網(wǎng)提供了非常詳細(xì)的wiki和視頻教程。與Swagger需要使用標(biāo)記語(yǔ)言編寫(xiě)不同，RAP可以完全可視化地定義項(xiàng)目相關(guān)信息，定義接口的請(qǐng)求響應(yīng)等等，學(xué)習(xí)成本較低。RAP還為后端開(kāi)發(fā)人員提供了校驗(yàn)接口的功能，為前端開(kāi)發(fā)人員提供了mock數(shù)據(jù)的工具等。

RAP的本地搭建過(guò)程如下：

1. 本地服務(wù)準(zhǔn)備：Tomcat、Redis、Mysql；

2. Github上下載RAP最新的war包，部署war包到Tomcat/webapps/ROOT目錄下；

3. 修改數(shù)據(jù)庫(kù)配置文件：ROOT/WEB-INF/classes/config.properties，修改為本地?cái)?shù)據(jù)庫(kù)的連接信息；

4. 數(shù)據(jù)庫(kù)初始化：在本地?cái)?shù)據(jù)庫(kù)上執(zhí)行ROOTWEB-INFclassesdatabase中的initialize.sql；

5. 開(kāi)啟tomcat、redis、mysql服務(wù)，瀏覽器訪(fǎng)問(wèn)http://localhost:8080/。

總結(jié)

總的來(lái)說(shuō)極力推薦eoLinker，在目前是最受歡迎的一款接口管理工具。Postman是一個(gè)測(cè)試向的API小工具，可以非常輕量地維護(hù)一份“測(cè)試記錄”，適合小的測(cè)試團(tuán)隊(duì)自己使用并維護(hù)。Swagger豐富且獨(dú)立的各個(gè)功能使得它可以被應(yīng)用在各種需求下，不論是開(kāi)發(fā)還是測(cè)試都可以使用這個(gè)工具，來(lái)優(yōu)化自己的開(kāi)發(fā)過(guò)程，進(jìn)行接口文檔維護(hù)、接口測(cè)試等；但Swagger的學(xué)習(xí)和接入成本相對(duì)較高，需要開(kāi)發(fā)與測(cè)試的深入配合。RAP的應(yīng)用范圍非常明確，是一個(gè)面向開(kāi)發(fā)人員自測(cè)和聯(lián)調(diào)的工具性平臺(tái)，它更適合以開(kāi)發(fā)為核心對(duì)接口進(jìn)行維護(hù)，供測(cè)試人員參考。