目錄
Swagger簡介 4
安裝 4
一、 Node.js 安裝 4
二、 node中http-server安裝 4
三、 下載swagger-editor 4
四、 啟動 swagger-editor 5
五、 使用瀏覽器訪問http://localhost 5
使用 5
一、 編寫API 文檔： 7
二、 生成服務端代碼： 8
三、 修改&運行服務端： 9
四、 創建&運行客戶端： 11
1． 使用swagger-editor 的web 界面： 11
2． 使用swagger-editor生成的客戶端代碼 14
3． 使用chrome 的 postman 插件 15
Swagger簡介
Swagger包括Swagger Editor， Swagger UI等很多部分，這里我們主要講一下Swagger Editor。它是一個完全開源的項目，並且它也是一個基於Angular的成功案例。
在Swagger Editor中，我們可以基於YAML等語法定義我們的RESTful API，然后它會自動生成一篇排版優美的API文檔，並且提供實時預覽。簡單說就是可以邊編寫API 邊預覽邊測試。
在Swagger UI中，我們不能進行編寫API ，但是我們可以預覽或者測試。
安裝
一、Node.js 安裝
swagger 是用node寫的，所以需要先按照node。安裝nodejs后node和npm會一並安裝。
windows 中 直接運行node-v8.1.2-x64.msi 即可完成安裝（我已經下載好，位於： \\10.9.60.201\shares\）
二、node中http-server安裝
任一cmd窗口，執行npm install -g http-server
三、下載swagger-editor
安裝swagger-editor 有多種方式，
l 從github 下載安裝。 這個方式可能行不通，因為下載通常很慢。
l 從官網下載swagger-editor.zip，解壓即可。(已共享)
四、啟動 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
結果：
說明：
界面左邊是api 文件的 yaml 描述文件， 左邊部分可以直接編輯API文檔，編輯會立即更新到右邊視圖。右邊是swagger-UI，可以查看文檔，並直接進行API的測試。
使用
l 示例。
swagger 內置了很多個examples。通過File→Open Example… 打開各示例文檔：
l 設置。
通過 Preference可以進行各種偏好設置：
一、編寫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 微服務。代碼結構如下：
三、修改&運行服務端：
l Spring 服務端： spring-server-generated.zip
src\main\java\io\swagger\api包下面的所有Api/ApiController結尾的類需要修改， 如PetIdApi 、 PetIdApiController 中所有的Void 改成 Pet。
ApiController結尾的類的public方法需要完成一些mock操作， 也就是—— // do some magic!
public ResponseEntity<Pet> petIdGet(@ApiParam(value = "ID of the pet",required=true ) @PathVariable("petId") String petId, HttpServletRequest request) {
// do some magic!
System.out.println("petId = " + petId);
Pet pet = new Pet();
pet.setName("lk 111");
pet.setBirthday(1234);
HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.TEXT_PLAIN);
ResponseEntity<Void> responseEntity = new ResponseEntity<>(headers, HttpStatus.OK);
ResponseEntity<Pet> ok = responseEntity.ok(pet);
return ok;
}
修改完成后雙擊運行 項目的maven 構建： spring-boot 即可：
由於某些原因， swagger生成的Spring 服務端代碼沒有UI 界面， 也就是 沒有 swagger-UI。 當然， 只要我們簡單修改，就完成UI 功能：
將swagger-editor-UI.zip（已共享） 放到web根目錄，稍作修改即可。
l Swagger-editor 生成的nodejs 服務端代碼（推薦）， 不用修改就可以直接運行：
解壓nodejs-server-server-generated.zip ， 然后cmd 進入nodejs-server-server 目錄，npm start 即可運行，訪問http://localhost:8080/docs 可以看到swagger-UI ：
然后， 我們就可以進行測試等操作。
四、創建&運行客戶端：
服務端啟動之后， 就可以進行訪問測試。訪問測試有多種方式，
1 是直接使用swagger-editor 的web 界面
2 是使用swagger-editor生成的客戶端代碼
3 是使用瀏覽器插件， 比如chrome 的 postman 插件
下面分別進行介紹：
1．使用swagger-editor 的web 界面：
舉個栗子，我們現在准備測試GET /pets/{id} ：
右邊視圖 -> /pets/{id} -> Try this operation , 填好參數，然后點擊“Send Request”
不過，發送請求進行測試之前，我們需要做兩件事：
1 由於我們是在瀏覽器中進行測試不同網站的接口。 我們實際上已經跨域，出於安全原因，瀏覽器默認不允許跨域。故我們需要做一些處理，比如安裝一些插件。Chrome 上安裝一個Allow-Control-Allow-Origin 拓展：
（chrome 拓展文件為www.cnplugins.com_fhbjgbiflinjbdggehcddcbncdddomop_4_7_2_.crx， 已共享， 如果無法安裝， 那么需要從chrome 商店進行下載-安裝， https://chrome.google.com/webstore/category/extensions?hl=zh-CN）
2 由於當前版本的swagger-editor 本身存在一些問題（發送的請求無法設置Content-Type請求頭）， 我們需要修改我們的后端代碼：
src\main\java\io\swagger\api包下面的所有Api結尾的類需要修改，將其中每個方法的RequestMapping 部分的 consumes 去掉：
后端代碼修改完需要重啟。
處理完畢，我們就可以進行API 接口測試了：
2．使用swagger-editor生成的客戶端代碼
swagger-editor可以生成 很多語言版本的客戶端代碼， 個人認為其中 JavaScript、java 比較有研究價值的，
由於某些原因，部分語言可能無法生成代碼:
如同swagger-editor生成的服務端代碼， 其生成的客戶端代碼也可能有問題。需要做一些修改：
以生成的java代碼為例， 需要將 src\main\java\io\swagger\api包下面的所有Api結尾的類需要修改， 其中的Void 改成 Pet。
src\test\java\io\swagger\client\api 包的類需要修改， 其中的Void 改成 Pet。
運行測試方法， 完成測試：
3．使用chrome 的 postman 插件
下載安裝postman，
運行：
設置請求頭：
Postman 的具體用法請查看網絡相關資料，此處不再贅述。