源 /         文/ 夢(mèng)想de星空

Swagger經(jīng)常被人吐槽界面不夠好看、功能不夠強(qiáng)大，其實(shí)有很多工具可以和Swagger結(jié)合使用，結(jié)合之后就會(huì)變得非常好用。有朋友留言說(shuō)YApi也很好用。最近體驗(yàn)了一把YApi，發(fā)現(xiàn)確實(shí)不錯(cuò)，推薦給大家！

YApi簡(jiǎn)介

YApi是高效、易用、功能強(qiáng)大的API管理平臺(tái)，旨在為開(kāi)發(fā)、產(chǎn)品、測(cè)試人員提供更優(yōu)雅的接口管理服務(wù)。YApi在Github上已累計(jì)獲得了18K+Star，具有優(yōu)秀的交互體驗(yàn)，YApi不僅提供了常用的接口管理功能，還提供了權(quán)限管理、Mock數(shù)據(jù)、Swagger數(shù)據(jù)導(dǎo)入等功能，總之功能很強(qiáng)大！

安裝

環(huán)境準(zhǔn)備

本地部署YApi需要先安裝nodejs和MongoDB，我們先把它們安裝好。

• 安裝nodejs，直接下載安裝包雙擊安裝即可，這里安裝的是12.14.0版本，下載地址：https://nodejs.org/dist/v12.14.0/node-v12.14.0-x64.msi;

• 安裝MongoDB，參考《MongoDB快速入門，掌握這些剛剛好！》中的安裝即可，這里安裝的是4.2.5版本。

安裝yapi-cli

yapi-cli是YApi官方提供的安裝工具，可以通過(guò)可視化界面來(lái)部署YApi服務(wù)，非常方便！

• 使用npm命令來(lái)安裝yapi-cli：

npm install -g yapi-cli --registry https://registry.npm.taobao.org

• 安裝成功后控制臺(tái)輸出如下內(nèi)容；

• 安裝成功后使用yapi server命令來(lái)啟動(dòng)YApi的可視化部署界面。

yapi server

安裝YApi

• 通過(guò)可視化部署界面安裝YApi服務(wù)，訪問(wèn)地址：http://localhost:9090

• 安裝完成后會(huì)輸出如下信息，提示YApi的默認(rèn)管理員賬號(hào)密碼及訪問(wèn)地址；

• 進(jìn)入YApi的安裝目錄，使用node命令啟動(dòng)YApi服務(wù)：

node vendors/server/app.js

• 啟動(dòng)成功后控制臺(tái)輸出信息如下；

• 通過(guò)頁(yè)面訪問(wèn)Yapi，默認(rèn)賬號(hào)密碼為[email protected]:ymfe.org，訪問(wèn)地址：http://localhost:3000

使用

從Swagger導(dǎo)入數(shù)據(jù)

• 使用管理員賬號(hào)登錄成功后，先創(chuàng)建一個(gè)mall-tiny-group分組；

• 創(chuàng)建分組成功后，在該分組下點(diǎn)擊創(chuàng)建項(xiàng)目，添加mall-tiny-swagger項(xiàng)目；

• 之后啟動(dòng)我們之前的mall-tiny-swagger項(xiàng)目，啟動(dòng)成功后Swagger接口文檔訪問(wèn)地址：http://localhost:8088/swagger-ui/

• 選擇好YApi的數(shù)據(jù)管理功能，配置好Swagger的api-docs路徑，然后進(jìn)行數(shù)據(jù)導(dǎo)入；

• 至此Swagger中的API接口已成功導(dǎo)入到Y(jié)Api，點(diǎn)擊接口標(biāo)簽查看所有導(dǎo)入接口。

接口管理

• 打開(kāi)添加商品的接口看看，可以看到非常完善的接口文檔信息，注釋都有了；

• 來(lái)試試接口運(yùn)行功能，我們會(huì)發(fā)現(xiàn)默認(rèn)的接口請(qǐng)求地址并不符合我們的要求，需要在環(huán)境配置中設(shè)置；

• 由于是跨域請(qǐng)求，Chrome瀏覽器需要安裝跨域請(qǐng)求插件，下載地址：https://github.com/YMFE/cross-request/archive/master.zip

• 由于我們的部分接口在請(qǐng)求頭中添加token才能訪問(wèn)，所以我們先調(diào)用登錄接口獲取token；

• 之后在設(shè)置->環(huán)境配置中添加Authorization頭；

• 再次調(diào)用需要登錄的接口，可以正常獲取到數(shù)據(jù)，返回?cái)?shù)據(jù)雖然格式化了，但是沒(méi)有折疊功能，數(shù)據(jù)太長(zhǎng)的話就不太好看了；

Mock功能

• 在我們調(diào)用POST接口提交JSON數(shù)據(jù)時(shí)，默認(rèn)Mock的JSON數(shù)據(jù)有點(diǎn)不太符合我們的要求；

• 可以通過(guò)接口信息中的編輯->高級(jí)設(shè)置進(jìn)行修改；

• 我們可以發(fā)現(xiàn)每一個(gè)接口信息中都有個(gè)Mock地址，當(dāng)我們后臺(tái)接口已經(jīng)定義好格式，但是沒(méi)有實(shí)現(xiàn)時(shí)，前端可以使用該地址來(lái)Mock數(shù)據(jù)進(jìn)行調(diào)試；

• 調(diào)用Mock地址可以獲取到一些測(cè)試數(shù)據(jù)，數(shù)據(jù)取值返回可以通過(guò)上面的Mock設(shè)置自行修改；

從Swagger自動(dòng)同步

• 當(dāng)我們的接口修改了，API文檔如何同步呢，我們可以通過(guò)設(shè)置->Swagger自動(dòng)同步來(lái)開(kāi)啟自動(dòng)同步功能，有三種數(shù)據(jù)同步模式可以選擇；

權(quán)限管理

如果有新的成員加入進(jìn)來(lái)，需要查看API文檔怎么辦？

• 首先可以通過(guò)注冊(cè)界面注冊(cè)一個(gè)成員賬號(hào)，此處賬號(hào)為[email protected]:123456；

• 之后使用管理員賬號(hào)登錄，然后通過(guò)成員列表->添加成員，將用戶添加到相應(yīng)分組；

• 最后使用成員賬號(hào)登錄即可訪問(wèn)相應(yīng)API文檔了。

總結(jié)

YApi結(jié)合Swagger使用果然很強(qiáng)大！之前使用Postman結(jié)合Swagger使用時(shí)，文檔查看、自動(dòng)同步的問(wèn)題都得到了解決，為了保證我們API文檔訪問(wèn)的安全性還提供了權(quán)限管理功能。當(dāng)API數(shù)據(jù)格式定義好后，Mock功能讓前端無(wú)需后臺(tái)實(shí)現(xiàn)也可以調(diào)試接口。不過(guò)對(duì)于JSON格式支持有點(diǎn)偏弱，要是能對(duì)JSON數(shù)據(jù)進(jìn)行折疊顯示就更好了！

參考資料

官方文檔：https://hellosean1025.github.io/yapi/documents/index.html

項(xiàng)目源碼地址

https://github.com/macrozheng/mall-learning/tree/master/mall-tiny-swagger