兼顧測試功能的API文件管理工具：Swagger與RAP2

超頻化石魚發表於2018-11-07
APISwagger

常規的開發流程通常為：後端提供API文件→前後端各自實現→聯調測試。

這裡經常遇到的兩個問題：

  1. 文件如何維護。
  2. 一方實現後，需要等另一方進行聯調。

對於文件的維護，常規的API文件管理工具都具備文件的建立、修改、共享、版本記錄等，差別不大。

而對於聯調的等待問題，會大大降低開發的效率。於是出現了Mock：前端可以使用Mock設定介面與返回資料，當進行請求時，攔截請求，並返回設定的資料。於是前端不與服務端進行聯調即可測試。同理，服務端可以使用Mock來模擬前端請求，直接自測。且無論前後端，Mock對程式碼的入侵性都非常小。

然而Mock最大的問題在於，前後端使用的API文件必須沒有出入。若一方擅自變更了文件而沒有通知另一方，那麼就會導致雙方使用的介面不一致。另外，若一方不小心看錯了文件，也會導致開發的介面出現問題。

目前很多API文件管理工具除了提供對API的管理，還提供Mock功能。即將文件編寫完成後，API文件管理工具還可以作為一個服務跑起來，前端可以直接請求該服務來訪問定義的介面，感覺就像一個真正的後端；也可以將文件匯出到Postman等，直接模擬前端請求來訪問後端。

於是，前後端不再需要在專案中加入Mock程式碼，而是改為訪問這個中間Mock服務。

 

目前API文件管理工具有很多。但有的功能有限，有的需要使用資料庫，有的收費。比較好用且開源的，就是Swagger與RAP2了。

Swagger

Swagger官網：

https://swagger.io/

Swagger使用Swagger UI來顯示文件。官方提供的GitHub原始檔中有一個dist資料夾，就是Swagger UI。將其放到Tomcat下即可訪問。

至於文件資料，全部儲存在一個json檔案中。將該檔案放在dist目錄下，然後修改dist/index.html中的SwaggerUIBundle.url指向該json檔案即可。

url路徑需要使用：ip:埠/資料夾名稱/json檔名。

例如：

const ui = SwaggerUIBundle({
	  url: "http://192.168.1.98:8080/swagger/swagger.json",
        ...
})

也就是Tomcat部署後，從瀏覽器中訪問該json檔案所用的路徑。

然後從瀏覽器中開啟該index.html即可看到文件。

至於文件的編寫，官方提供了Swagger Editor，功能很強大，可以匯入匯出，甚至根據API來生成程式碼。但使用的是yaml語法，要手動寫文件，就必須使用官方規定的格式來手寫yaml，雖然提供了邊改邊看功能，但依然非常不友好，很難用。那感覺就像在用記事本寫java。

Swagger幾乎沒有第三方的編輯器，國內的sosoapi提供了一個線上的版本，可以線上以介面的形式對Swagger進行編輯，相比於Swagger Editor友好了很多。唯一煩瑣的一點是介面響應的欄位型別和Mock是分開的，因此需要先定義介面的每個欄位是什麼型別，然後再定義Mock返回值。雖然支援json匯入，但依然是要操作兩次的。另外編輯介面上並不會直接展示已經定義的Mock返回值是多少，需要點開Mock設定來看。

sosoapi的文件需要線上編輯和維護，也有離線版本，功能會受限制。

sosoapi支援將文件匯出為各種格式，其中就包含Swagger所用的json格式。因此可以將匯出的json放在Tomcat下讓index.html來訪問。但sosoapi本身對json進行了擴充套件，所以Swagger的index.html並不能完全正確地識別。推薦使用sosoapi線上的API管理功能。

sosoapi對前端提供可直接訪問的Mock服務。也可以通過設定介面令牌（即服務端埠），來測試後端的介面。

RAP2

RAP2官網：

http://rap2.taobao.org/

RAP2也是線上使用的，支援離線部署。

RAP2功能與sosoapi基本相同，但其展示功能更好，編輯功能也強大，對於介面的響應欄位只需要匯入一次，即可直接生成欄位名稱，型別和Mock資料，更方便。

但RAP2匯出功能相對較少，且不具備根據API來生成程式碼的功能。

RAP2同樣對前端提供可直接訪問的Mock服務。

對於後端的測試，RAP2可匯出為Postman Collection，從Postman中匯入後，設定基地址，即可直接訪問後端介面。

 

Swagger推薦使用sosoapi。sosoapi與RAP2相比，sosoapi功能更豐富，但相對要了解的內容要多一些，同時展示和操作上有一些不太方便的地方。RAP2功能少一些，但操作方便，更加友好。然而二者都具備API文件管理與Mock測試這兩個核心功能，所以實際開發時用起來區別不大。

相關文章