功能強大的swagger-editor的介紹與使用

1、Swagger Editor簡介

Swagger Editor是一個開源的編輯器，而且它也是一個基於Angular的成功案例。在Swagger Editor中，咱們能夠基於YAML等語法定義咱們的RESTful API，而後它會自動生成一篇排版優美的API文檔，而且提供實時預覽。簡單說就是能夠邊編寫API 邊預覽邊測試。

Swagger官方提供了一個Swagger Editor的在線的web版本，http://editor.swagger.io/#/，固然咱們也能夠下載到本身的機器在本地運行。

2、Swagger Editor安裝

1.Node.js 安裝

swagger 是用node寫的，因此須要先安裝node。安裝nodejs後node和npm會一併安裝。windows中直接運行node-v8.1.2-x64.msi便可完成安裝。

2.node中http-server安裝

任一cmd窗口，執行

npm install -g http-server

 

3.下載swagger-editor

安裝swagger-editor 有多種方式，

從github 下載安裝（有時下載會有點慢）

從官網下載swagger-editor.zip，解壓便可。（已共享到QQ羣文件：301343109）

3、啓動Swagger Editor

在swagger-editor的根目錄打開cmd窗口，執行http-server ，默認爲8080端口 ，若想更換端口則使用以下命令 http-server –p 80 或者修改：C:\Users\Administrator\AppData\Roaming\npm\node_modules\http-server\bin\http-server 中 84行 portfinder.basePort = 8080; 改成本身想要的端口。

 

使用瀏覽器訪問http://localhost:8080

 

說明：

界面左邊是api 文件的 yaml 描述文件， 左邊部分能夠直接編輯API文檔，編輯會當即更新到右邊視圖。右邊是swagger-UI，能夠查看文檔，並直接進行API的測試。

4、使用Swagger Editor

1.示例

swagger 內置了不少個examples。經過File→Open Example… 打開各示例文檔：

 

2.設置

經過 Preference能夠進行各類偏好設置：

 

3.編寫API 文檔

咱們能夠參照swagger-editor的示例，直接修改，而後生成本身的文檔。

幾個關鍵地方須要修改：

host 改成本地ip:port

basePath 改成項目名或模塊名

 

swagger-editor 有自動糾錯的功能，編寫的API 文檔應該保證沒有錯誤。這樣才能發佈。

編寫完畢後， 咱們能夠把它保存下來。 可選格式爲yaml/json ：

 

固然，咱們也能夠把寫好的yaml/json 文檔導入而後修改、測試。

五、生成服務端代碼

Swagger-editor的強大功能，在於其能夠生成不少種語言的服務端/客戶端代碼， 同時服務端代碼中包含了Swagger-UI。 以下， 我的認爲服務端中 其中 Node.js、Python Flask、Spring 語言的代碼比較有價值，值得研究。

 

Spring 服務端代碼適合後端開發人員，可是其生成的代碼比較簡單，並且不能直接使用， 須要作一些修改。

生成代碼前， 咱們確保已修改咱們文檔的關鍵地方：

host: localhost:8080

basePath: /projectABC

以 Swagger Petstore (Simple) 爲例， 生成的spring 服務端代碼本質上是一個spring-boot 微服務。代碼結構以下(導入eclipse)（已共享到QQ羣文件：301343109）：

六、修改&運行服務端

打開application.properties文件，原來的server.port是8080，我這邊有衝突，因此改爲8060。

運行Swagger2SpringBoot類的main方法：

 

 看到紅色矩形裏的文字就表明啓動成功了。

 

訪問http://localhost:8060/projectABC/swagger-ui.html能夠看到swagger生成的api文檔了：

 

而後， 咱們就能夠進行測試等操做。

七、建立&運行客戶端

服務端啓動以後， 就能夠進行訪問測試。訪問測試有多種方式，

1 是直接使用swagger-editor 的web 界面

2 是使用swagger-editor生成的客戶端代碼

3 是使用瀏覽器插件， 好比chrome 的 postman 插件

下面分別進行介紹：

1．使用swagger-editor 的web 界面

舉個栗子，咱們如今準備測試get /estimates/price：

 

2.使用swagger-editor生成客戶端代碼

swagger-editor能夠生成 不少語言版本的客戶端代碼， 我的認爲其中 JavaScript、java 比較有研究價值的，

 

具體參照

swagger-codegen自動生成代碼工具的介紹與使用

3．使用chrome 的 postman 插件

下載安裝postman

 

運行：

 

設置請求頭：

Postman 的具體用法請查看網絡相關資料，此處再也不贅述。