本文章描述的是Swagger3.0的內容，與Swagger2.0內容有較大差別。接口描述在3.0中通過Swagger規範（一個JSON文件）來描述，Swagger2.0是通過在接口中提供一係列注解來描述的。

 

1.集成Swagger 

      Swagger提供了一組靜態頁麵，可以在SpringBoot應用中集成這些靜態頁麵，直接訪問靜態頁麵，並打開指定的Swagger規範，就可以顯示RESTFul接口：

進入Swagger官網，選擇Swagger UI，點擊下載。頁麵會跳轉到GitHub在GitHub中，選擇一個最新的版本下載，目前最新的是Swagger UI 3.20.5.下載解壓後，找到dist目錄，將目錄裏麵所有的文件複製到新的SpringBoot項目中src\main\resources\static\swagger3\目錄下麵。訪問http://localhost:8080/swagger3/index.html，會出現如下界麵。

  該頁麵加載的時候，會自動打開一個swagger接口規範文檔，如上圖輸入框中所示：http://petstore.swagger.io/v2/swagger.json。

  打開後的頁麵分為兩部分，第一部分為接口的基本信息，包含了項目名稱，描述等信息；第二部分包含了每個接口的具體描述，如接口名字，參數名字，參數類型，是否必填等，還有返回的結果的示例。

注意：默認提供的Petstore接口調用並不能成功，因為這涉及跨域問題，在localhost環境下發起對petstore.swagger.io的AJAX調用會導致失敗。

2.Swagger規範

    swagger規範是一個JSON格式的文件，包含項目基本信息及具體接口描述信息，可以在swagger3下創建一個sample.json文件，草莓视频黄片在线看將逐漸完善。

{ "swagger":"2.0", "info":{ "description":"這是一個項目簡單實例", "version":"1.0", "tirle":"係統接口", }, "basePath":"/api/v1", "consumes":[ "application/x-www-form-urlencode" ]} 屬性swagger總是規範的第一個屬性，固定為2.0，指的是Swagger規範2.0。info描述了一個項目的基本信息。basePath：指的是RESRFul接口的實際地址，以上是/api/v1，則REST接口的地址則是127.0.0.1:8080/api/v1。consumes：指提交的內容是表單。

重新訪問網址http://localhost:8080/swagger3/index.html，並且在頁麵填寫規範地址：

http://localhost:8080/swagger3/sample.json

點擊Explore按鈕，頁麵刷新後，如下所示：

3.接口描述

 

"paths":{ "/order/{orderId}":{ "get":{ "summary":"獲取訂單詳細信息", "description":"傳入訂單編號，獲取訂單信息", "parameters":[ { "name":"orderId", "in":"path", "description":"訂單Id", "required":true } ], "responses":{ "200":{ "description":"獲取用戶信息成功" } } } } }

每個接口包含了以下信息：

summary：接口主要功能的簡要描述description：接口詳細描述parameters：接口的參數，REST參數在Swagger中分為四個類型，以上實例的參數類型是path，也就是參數是從path中獲取的，其他的還有body，parameter等。response：對應了HTTP status的提示信息，這裏描述了成功的提示信息。4.查詢參數描述

 

"parameters":[ { "name":"offset", "in":"query", "description":"查詢起始位置", "required":true } ] http://localhost:8080/api/v1/order?offset=12 5.HTTP頭參數 "parameters":[ { "name":"X-Request-ID", "in":"header", "description":"", } ] 6.表單參數

使用application/x-www-form-urlencoded提交的參數，in的值使用formData。

"parameters":[ { "name":"orderName", "in":"formData", "description":"", "required":true } ] 7.文件上傳參數  "parameters":[ { "name":"orderName", "in":"formData", "description":"", "type":"file" } ] 8.整個請求體作為參數 "/order":{ "post":{ "summary":"創建訂單", "description":"創建一個新訂單", "parameters":[ { "name":"order", "in":"body", "description":"包含訂單信息的JSON", "required":true, "schema":{ "$ref":"#/definitions/order" } } ], "responses":{ "200":{ "description":"創建訂單成功" } } } } "definitions":{ "order":{ "type":"object", "properties":{ "id":{ "type":"string" }, "name":{ "type":"string" } } } }

 

 

未完待續...