搭建swagger-mock-server的一個嘗試

時間 2019-12-09

標籤搭建 swagger mock server 一個嘗試简体版

原文原文鏈接

內容概要

概要
Mock Server
UI
Editor
安裝使用和工做流
參考資源

簡介

在先後端分離的企業api開發流程中，有時候會面臨前端同窗等待後端同窗實現接口的狀況。
爲了不時間上的浪費，能夠採起先制定API文檔再先後端並行開發的方式。
前端同窗能夠直接調用接口得到臨時性的假數據，而不影響工做流暢性。前端

Swagger規範是一種通用的api文檔格式，本文記錄的是根據swagger文檔自動生成假數據的一次嘗試。node

項目Github地址見: imnisen/swagger-mock-server 。git

聲明：這個項目還不完善，目前的階段是：「能用」。距離達到「清晰合理的架構」，「簡單明瞭的開發部署」，「完善的功能」目標還須要努力。若是你有更好的作法或者意見建議歡迎經過issuse或者email聯繫我。github

該項目實現的功能是：根據swagger文檔，mock server 來生成假數據，這樣便於實際開發中，定義好api後，先後端並行開發。docker

該項目除了mock server之外還包含了查看接口ui和開發時使用的editor.express

Mock Server

「Mock server」的實現是基於swagger的這個node 項目， server目錄 下面的內容是執行參考這裏生成的。npm

爲了支持多種假數據生成的要求，對依賴的一個模塊進行了hack, 因此安裝使用的時候會發現有這麼一步: cp swagger-router.js node_modules/swagger-tools/middleware/swagger-router.js, 其實是替換了 swagger-router.js 裏107行 getMockValue 函數。json

這個hack的方法是參考了這篇博文，而後修復實際使用中發現的一些問題。後端

UI

UI部分是採用的官方的ui工具，爲了方便直接將內容提取到了 ui/dist目錄 下，該目錄對應於這個 github目錄便於之後「手工升級」(汗)。api

Editor

實際使用的體驗是，mock server對於swagger語法解析的要求要比ui要求嚴格，也就是說有些不合swagger規範的寫法ui能夠辨識，但卻會致使mock server 不能正常解析以致於不能正常啓動，因此擁有一個嚴格的swagger語法編輯器顯得挺重要。官方提供了swagger editor，但它不能方便地選擇默認編輯的文件和自動保存，因此每次使用時得手動選擇要編輯的文件，編輯完以後再保存回去，這使得總體流程有些複雜。好在上面的swagger node項目裏包含了 swagger editor，因此我在 server/package.json 裏簡單配置了下，可使用 npm run edit 命令直接運行一個監聽9999端口的editor, 該editor直接編輯 doc/swagger.yaml 文件，而且全部改動會自動保存。

並且編輯swagger文件應該是開發階段的行爲，因此構建服務的時候，swagger editor並無暴露出來對外使用（也就是說不能直接修改服務端的swagger文檔）。另一點是我尚未找到合適的方法。在服務器端使用docker部署時按需求定製swagger editor。留待之後探究。

安裝使用和工做流

分位兩個階段：開發和部署。

開發的時候，由於要使用到editor因此推薦本地安裝，依賴 npm ，須要全局安裝npm包 swagger,而且在 server 目錄下執行 npm install 來安裝所需依賴，最後將hack的 swagger-router.js 複製到對應位置，啓動的時候經過 npm run server 和 npm run edit 分別啓動 mock server 和打開編輯器， swagger ui 也能夠啓動，經過 docker-compose up -d swagger_ui 來啓動，而且在7777端口能夠查看，但由於有editor，其提供了視圖因此不是很必須。

部署的時候不須要使用editor,因此使用docker compsoe能夠直接啓動mocker 和 ui, 而且經過7777和8888訪問， server/Dockerfile 裏幹掉了大部分上面須要手動作的事情，仍是比較方便的。

具體安裝還請參考github項目裏說明