【Swagger】Swagger Editor學習分享

「Swagger Editor」顧名思義是一個編輯器，那「swagger」又是什麼呢？

Swagger是什麼

Swagger 是一個功能強大的框架，用於設計、構建、歸檔、調試 RESTful 風格的API。它包含一套描述RESTful API 的規範格式（Swagger Specification）和若干個實用工具（Swagger Editor、Swagger Codegen、Swagger UI）等。Swagger 的目標是定義一個標準的、語言無關的 RESTful API 接口，不須要閱讀源碼和文檔，就可讓開發者和機器可以發現和理解服務的接口。 本文主要是關於 Swagger Editor 的學習和分享。

Swagger Editor 的安裝

Swagger Editor 官網有安裝步驟，網上也相關的教程，不過我安裝的過程當中老是碰到一些莫名其妙的錯誤，致使安裝失敗。通過摸索，仍是本身總結出了經驗，僅供參考。

首先，Swagger Editor 的運行依賴 Node JS，因此本地要先安裝 node 環境。node 安裝好之後，在命令行運行查看 node 是否安裝成功。

node -v

查看 npm 版本，npm是隨同NodeJS一塊兒安裝的包管理工具，能解決NodeJS代碼部署上的不少問題，相似於Cent OS上的yum。

npm -v

因爲網絡緣由，用npm安裝包可能會比較慢，可使用國內的淘寶鏡像。命令行執行

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

以後就能夠用 cnpm 命令代替 npm 命令了。

而後，在 GitHub 上下載 swagger-editor，不過打包好的文件老是下載失敗，只能下載原碼，本地打包原碼又會報不少看不懂的錯誤，怎麼辦呢？ 咱們能夠用 npm 來得到 swagger-editor。在命令行執行

npm install swagger-editor

就會在當前目錄的 node_module 文件夾下看到 swagger-editor 了。

另外，還須要一個http服務器來加載項目中的靜態文件，通常能夠用http-server。命令行執行

npm install -g http-server

全局安裝http-server。安裝好之後，在 swagger-editor 所在目錄用命令行執行

http-server -p 8000 swagger-editor

-p 是指定訪問端口，在瀏覽器中訪問 http://localhost:8000 就能進入編輯頁面了。

或者用文本編輯器打開 swagger-editor 文件夾下的package.json，找到

"scripts": {
    "start": "node server.js",
}

修改成

"scripts": {
    "start": "http-server -p 8000",
}

而後打開命令行，切換到 swagger-editor 目錄下，執行

npm start

就能啓動項目了。

也能夠用 tomcat 來部署 Swagger Editor，將 Swagger Editor文件夾放到 tomcat 的 webapp 目錄下，啓動tomcat，而後在瀏覽器訪問 http://localhost:8080/swagger-editor

Swagger Editor 的使用

Swagger Editor 使用 yaml 格式描述 API，它的編輯界面相似於Markdown，左邊是文本，右邊是預覽頁面，能夠實時顯示編輯效果和格式校驗。

Swagger Editor 還能自動生成不一樣平臺的服務端和客戶端，方便先後端開發人員進行測試。

服務端

如圖，以Spring項目爲例，生成一個Spring架構的服務端，在Eclipse中導入項目。

因爲該項目使用了spring-boot，咱們能夠從 Swagger2SpringBoot 直接啓動項目，默認端口是8080。 在 API 編輯頁面每一個接口的下面有個 「Try this operation」 按鈕，點擊會展開測試 API 的界面，可編輯協議、accept類型、參數等。

在左側 API 編輯頁面把 host 改成本地服務地址，填寫參數後點擊 Send Request，請求就能發送到服務端了。 可是可能會出現跨域問題，致使請求的響應失敗。

警告的最後有解決的辦法

⚠️ This is a cross-origin call. Make sure the server at localhost:8080 accepts GET requests from localhost:8000. Learn more

這裏我選擇在服務端啓用 CORS 的方法，就是在 response 的 header 中設置

Access-Control-Allow-Origin: editor.swagger.io

Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept

這兩項。

服務端的代碼中已經有了這樣一個過濾器 ApiOriginFilter，可是彷佛沒起做用。緣由是這個類上面沒加 @Component 註解。 加上註解以後，重啓服務，瀏覽器就能收到正確的響應了。

客戶端

選擇語言生成客戶端，導入項目，修改 ApiClient 中的服務地址

而後跑單元測試就行了。