Swagger環境搭建之非依賴代碼法

前言

Swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。整體目標是使客戶端和文件系統做爲服務器以一樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，容許API來始終保持同步。Swagger 讓部署管理和使用功能強大的API從未如此簡單。好吧，以上是官方的說法，我直接複製的，在我看來swagger就是一個接口文檔管理器，之前咱們寫接口通常都是world編寫，可是有一個問題就是測試的時候須要依賴第三方工具，GET的接口還好，直接瀏覽器打開，POST的只能依賴另外的工具了，而Swagger呢，能夠直接經過代碼中的註解生成接口文檔（JavaEE）,通常人都用這種方式，並且直接集成在項目中，方便成員查看，同時還能直接測試，另外Swagger的界面也不錯，也許這就是我選擇用Swagger的緣由吧，直接官方說的RESTful 風格那個不用管，不是RESTful 風格的接口也能用，固然Swagger還有一種方式就是手動寫接口說明了，這樣的好處就是代碼只有代碼，由於一旦代碼中添加了Swagger的接口註解後，代碼量仍是增長了很多，固然壞處就是你改完了代碼，還要去改接口文檔，而本文主要介紹第二種方式

關鍵點

Swagger-UI

Swagger-edit在線版

Swagger-edit

Swagger-UI

其實就是靜態的HTML、js、css文件，從github上下載下來，打開dist目錄下的index.html，就能從運行起來了，不過默認是swwager demo的接口文檔，以下圖： Swagger主要經過json文件來實現接口文檔和接口說明等功能，因此咱們在輸入框內輸入不一樣的json地址，就能打開不一樣的接口文檔

swagger-editor在線版

其實就是一個在線編輯接口文檔的網頁，剛纔說過，Swagger-ui展現出來的接口徹底依賴於的json的內容，因此咱們能夠經過Swagger-edit在線版來定製json的內容，不用本身寫json，固然Swagger-edit在線版也是經過yaml 標記語言來的，不過看一下demo，就會很容易學會，編寫完成後咱們能夠下載json文件到本地，供Swagger-ui使用，不過因爲某種鮮爲人知的緣由，Swagger-edit在線版的訪問速度那叫一個慢，因此通常咱們都會下載Swagger-Edit在本地來運行

swagger-editor

這個和Swagger-edit在線版是同一個東西，不過由於在線版的速度太慢，因此咱們須要在本地來運行一個Swagger-edit，這樣就不存在網絡卡等問題了

開始部署

下載相關文件

一、下載Swagger-UI

Swagger-UI，直接經過git clone或者下載zip均可以，使用到核心的東西就是下載下來的dist文件夾裏面的東西

二、下載swagger-editor

這一步不是必要的，若是你不想用默認在線版的，就能夠執行這一步，固然目前除了Swagger默認提供了一個在線的編輯器，還有第三方的，如sosoapi，全中文傻瓜式操做的，上手快速

下載時建議下載最新版的編譯後的包，在swagger-editor頁面中有說明當前最新的版本號和下載地址

三、下載和安裝nodejs

這一步就不詳細說了，處處都是教程，並且就算沒有教程，相信對於程序員來講安裝一個軟件也是垂手可得的事情，若是不想用這個，能夠直接跳過，查看tomcat運行swagger-editor

四、安裝http-server

使用node.js安裝http-server模塊，主要經過http-server模塊來啓用http服務，運行swagger-editor，經過命令

npm install -g http-server

不過因爲某些緣由，國內安裝可能會很是慢，這時候咱們就能夠用淘寶 NPM 鏡像,來加速 首先運行命令

npm install -g cnpm --registry=https://registry.npm.taobao.org

而後可能須要重啓cmd命令工具，運行

cnpm install -g http-server

這樣就能很快的安裝http-server了，一樣的道理，若是須要安裝其餘模塊，也能夠經過cnpm來安裝，而後經過cmd命令進入到Swagger-edit的根目錄，運行命令

http-server -p 8000

-p的做用是指定端口，後面的8000就是咱們指定的端口，訪問localhost:8000就能夠進入swagger-edit就能夠進入編輯界面了，左邊是編輯框，右邊是預覽界面，以下圖 固然這一步也不是必須的，若是不肯用經過http-server來運行swagger-editor，能夠經過tomcat來運行

tomcat運行swagger-editor

首先把swagger-editor目錄複製到tomcat根目錄的webapps，而後運行tomcat，訪問localhost:8080/swagger-editor就能夠了

五、導出json

因爲編寫接口文檔並不在本文檔的內容，因此關於編寫這裏就很少作描述，並且主要我以爲編寫也沒啥可說，直接跟着默認的接口文檔來改就能看出來大概了，因此直接到最後一步，編寫完成後導出json文件

點擊File->DownLoad json就會下載swagger.json文件

六、部署swagger-ui

首先把json文件複製到swagger-ui根目錄，修改index.html的引用json文件的url，最後直接打開index.html也行，部署到服務器也行，不過要注意index.html中引用的json文件的url必定要正確

結語

到此爲止部署swagger的步驟已經完成了，若是有不明白或者不清楚的地方，能夠留言交流