本文章描述的是Swagger3.0的內容,與Swagger2.0內容有較大差別。接口描述在3.0中通過Swagger規(guī)范(一個JSON文件)來描述,Swagger2.0是通過在接口中提供一系列注解來描述的。
?
1.集成Swagger?? ? ? Swagger提供了一組靜態(tài)頁面,可以在SpringBoot應用中集成這些靜態(tài)頁面,直接訪問靜態(tài)頁面,并打開指定的Swagger規(guī)范,就可以顯示RESTFul接口:
進入Swagger官網,選擇Swagger UI,點擊下載。頁面會跳轉到GitHub在GitHub中,選擇一個最新的版本下載,目前最新的是Swagger UI 3.20.5.下載解壓后,找到dist目錄,將目錄里面所有的文件復制到新的SpringBoot項目中src\main\resources\static\swagger3\目錄下面。訪問http://localhost:8080/swagger3/index.html,會出現(xiàn)如下界面。
? 該頁面加載的時候,會自動打開一個swagger接口規(guī)范文檔,如上圖輸入框中所示:https://petstore.swagger.io/v2/swagger.json。
? 打開后的頁面分為兩部分,第一部分為接口的基本信息,包含了項目名稱,描述等信息;第二部分包含了每個接口的具體描述,如接口名字,參數(shù)名字,參數(shù)類型,是否必填等,還有返回的結果的示例。
注意:默認提供的Petstore接口調用并不能成功,因為這涉及跨域問題,在localhost環(huán)境下發(fā)起對petstore.swagger.io的AJAX調用會導致失敗。
2.Swagger規(guī)范? ? swagger規(guī)范是一個JSON格式的文件,包含項目基本信息及具體接口描述信息,可以在swagger3下創(chuàng)建一個sample.json文件,我們將逐漸完善。
{ "swagger":"2.0", "info":{ "description":"這是一個項目簡單實例", "version":"1.0", "tirle":"系統(tǒng)接口", }, "basePath":"/api/v1", "consumes":[ "application/x-www-form-urlencode" ]} 屬性swagger總是規(guī)范的第一個屬性,固定為2.0,指的是Swagger規(guī)范2.0。info描述了一個項目的基本信息。basePath:指的是RESRFul接口的實際地址,以上是/api/v1,則REST接口的地址則是127.0.0.1:8080/api/v1。consumes:指提交的內容是表單。重新訪問網址http://localhost:8080/swagger3/index.html,并且在頁面填寫規(guī)范地址:
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:接口的參數(shù),REST參數(shù)在Swagger中分為四個類型,以上實例的參數(shù)類型是path,也就是參數(shù)是從path中獲取的,其他的還有body,parameter等。response:對應了HTTP status的提示信息,這里描述了成功的提示信息。4.查詢參數(shù)描述?
"parameters":[ { "name":"offset", "in":"query", "description":"查詢起始位置", "required":true } ] https://localhost:8080/api/v1/order?offset=12 5.HTTP頭參數(shù) "parameters":[ { "name":"X-Request-ID", "in":"header", "description":"", } ] 6.表單參數(shù)使用application/x-www-form-urlencoded提交的參數(shù),in的值使用formData。
"parameters":[ { "name":"orderName", "in":"formData", "description":"", "required":true } ] 7.文件上傳參數(shù)? "parameters":[ { "name":"orderName", "in":"formData", "description":"", "type":"file" } ] 8.整個請求體作為參數(shù) "/order":{ "post":{ "summary":"創(chuàng)建訂單", "description":"創(chuàng)建一個新訂單", "parameters":[ { "name":"order", "in":"body", "description":"包含訂單信息的JSON", "required":true, "schema":{ "$ref":"#/definitions/order" } } ], "responses":{ "200":{ "description":"創(chuàng)建訂單成功" } } } } "definitions":{ "order":{ "type":"object", "properties":{ "id":{ "type":"string" }, "name":{ "type":"string" } } } }?
?
未完待續(xù)...
?