swagger 基礎入門

目錄

 

Swagger簡介 4

安裝 4

1、 Node.js 安裝 4

2、 node中http-server安裝 4

3、 下載swagger-editor 4

4、 啓動 swagger-editor 5

5、 使用瀏覽器訪問http://localhost 5

使用 5

1、 編寫API 文檔： 7

2、 生成服務端代碼： 8

3、 修改&運行服務端： 9

4、 建立&運行客戶端： 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 ，可是咱們能夠預覽或者測試。

 

 

安裝

1、Node.js 安裝

swagger 是用node寫的，因此須要先按照node。安裝nodejs後node和npm會一併安裝。

windows 中 直接運行node-v8.1.2-x64.msi 便可完成安裝（我已經下載好，位於： \\10.9.60.201\shares\）

 

2、node中http-server安裝

任一cmd窗口，執行npm install -g http-server 

 

3、下載swagger-editor

安裝swagger-editor 有多種方式，

l 從github 下載安裝。 這個方式可能行不通，由於下載一般很慢。

l 從官網下載swagger-editor.zip，解壓便可。(已共享)

4、啓動 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; 改成本身想要的端口。

 

5、使用瀏覽器訪問http://localhost

結果：

 

 

說明：

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

 

使用

l 示例。

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

  

 

l 設置。

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

 

 

 

1、編寫API 文檔：

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

幾個關鍵地方須要修改：

• host 改成本地ip:port
• basePath 改成項目名或模塊名

•  

 

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

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

 

 

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

 

2、生成服務端代碼：

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

 

 

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

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

host: localhost:8080

basePath: /projectABC

以 Swagger Petstore (Simple) 爲例， 生成的spring 服務端代碼本質上是一個spring-boot 微服務。代碼結構以下：

 

3、修改&運行服務端：

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 ：

 

 

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

 

4、建立&運行客戶端：

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

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 的具體用法請查看網絡相關資料，此處再也不贅述。