本文章描述的是Swagger3.0的內(nèi)容，與Swagger2.0內(nèi)容有較大差別。接口描述在3.0中通過(guò)Swagger規(guī)范（一個(gè)JSON文件）來(lái)描述，Swagger2.0是通過(guò)在接口中提供一系列注解來(lái)描述的。

?

1.集成Swagger?

? ? ? Swagger提供了一組靜態(tài)頁(yè)面，可以在SpringBoot應(yīng)用中集成這些靜態(tài)頁(yè)面，直接訪(fǎng)問(wèn)靜態(tài)頁(yè)面，并打開(kāi)指定的Swagger規(guī)范，就可以顯示RESTFul接口：

進(jìn)入Swagger官網(wǎng)，選擇Swagger UI，點(diǎn)擊下載。頁(yè)面會(huì)跳轉(zhuǎn)到GitHub在GitHub中，選擇一個(gè)最新的版本下載，目前最新的是Swagger UI 3.20.5.下載解壓后，找到dist目錄，將目錄里面所有的文件復(fù)制到新的SpringBoot項(xiàng)目中src\main\resources\static\swagger3\目錄下面。訪(fǎng)問(wèn)http://localhost:8080/swagger3/index.html，會(huì)出現(xiàn)如下界面。

? 該頁(yè)面加載的時(shí)候，會(huì)自動(dòng)打開(kāi)一個(gè)swagger接口規(guī)范文檔，如上圖輸入框中所示：https://petstore.swagger.io/v2/swagger.json。

? 打開(kāi)后的頁(yè)面分為兩部分，第一部分為接口的基本信息，包含了項(xiàng)目名稱(chēng)，描述等信息；第二部分包含了每個(gè)接口的具體描述，如接口名字，參數(shù)名字，參數(shù)類(lèi)型，是否必填等，還有返回的結(jié)果的示例。

注意：默認(rèn)提供的Petstore接口調(diào)用并不能成功，因?yàn)檫@涉及跨域問(wèn)題，在localhost環(huán)境下發(fā)起對(duì)petstore.swagger.io的AJAX調(diào)用會(huì)導(dǎo)致失敗。

2.Swagger規(guī)范

? ? swagger規(guī)范是一個(gè)JSON格式的文件，包含項(xiàng)目基本信息及具體接口描述信息，可以在swagger3下創(chuàng)建一個(gè)sample.json文件，我們將逐漸完善。

{ "swagger":"2.0", "info":{ "description":"這是一個(gè)項(xiàng)目簡(jiǎn)單實(shí)例", "version":"1.0", "tirle":"系統(tǒng)接口", }, "basePath":"/api/v1", "consumes":[ "application/x-www-form-urlencode" ]} 屬性swagger總是規(guī)范的第一個(gè)屬性，固定為2.0，指的是Swagger規(guī)范2.0。info描述了一個(gè)項(xiàng)目的基本信息。basePath：指的是RESRFul接口的實(shí)際地址，以上是/api/v1，則REST接口的地址則是127.0.0.1:8080/api/v1。consumes：指提交的內(nèi)容是表單。

重新訪(fǎng)問(wèn)網(wǎng)址http://localhost:8080/swagger3/index.html，并且在頁(yè)面填寫(xiě)規(guī)范地址：

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

點(diǎn)擊Explore按鈕，頁(yè)面刷新后，如下所示：

3.接口描述

?

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

每個(gè)接口包含了以下信息：

summary：接口主要功能的簡(jiǎn)要描述description：接口詳細(xì)描述parameters：接口的參數(shù)，REST參數(shù)在Swagger中分為四個(gè)類(lèi)型，以上實(shí)例的參數(shù)類(lèi)型是path，也就是參數(shù)是從path中獲取的，其他的還有body，parameter等。response：對(duì)應(yīng)了HTTP status的提示信息，這里描述了成功的提示信息。4.查詢(xún)參數(shù)描述

?

"parameters":[ { "name":"offset", "in":"query", "description":"查詢(xún)起始位置", "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.整個(gè)請(qǐng)求體作為參數(shù) "/order":{ "post":{ "summary":"創(chuàng)建訂單", "description":"創(chuàng)建一個(gè)新訂單", "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ù)...

?