Swagger 經(jīng)常被人吐槽界面不夠好看、功能不夠強(qiáng)大，其實(shí)有很多工具可以和 Swagger 結(jié)合使用，結(jié)合之后就會(huì)變得非常好用。之前寫(xiě)過(guò)一篇文章《Swagger 界面丑、功能弱怎么破？用 Postman 增強(qiáng)下就給力了！》，有朋友留言說(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 快速入門(mén)，掌握這些剛剛好！》中的安裝即可，這里安裝的是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)入到 YApi，點(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ò)成員列表->添加成員，將用戶(hù)添加到相應(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