歡迎來(lái)到《圣博凱斯》變頻供水設(shè)備官網(wǎng)
精銳于專業(yè) / 卓然于品質(zhì) -- 20年專注于供水行業(yè),締造至臻品質(zhì) -- 服務(wù)熱線:0731-85783205 18932453205

Swagger UI 詳細(xì)講解

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

?

1.集成Swagger?

? ? ? Swagger提供了一組靜態(tài)頁(yè)面,可以在SpringBoot應(yīng)用中集成這些靜態(tài)頁(yè)面,直接訪問靜態(tài)頁(yè)面,并打開指定的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\目錄下面。訪問http://localhost:8080/swagger3/index.html,會(huì)出現(xiàn)如下界面。

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

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

注意:默認(rèn)提供的Petstore接口調(diào)用并不能成功,因?yà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)容是表單。

重新訪問網(wǎng)址http://localhost:8080/swagger3/index.html,并且在頁(yè)面填寫規(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":"獲取用戶信息成功" } } } } }

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

summary:接口主要功能的簡(jiǎn)要描述description:接口詳細(xì)描述parameters:接口的參數(shù),REST參數(shù)在Swagger中分為四個(gè)類型,以上實(shí)例的參數(shù)類型是path,也就是參數(shù)是從path中獲取的,其他的還有body,parameter等。response:對(duì)應(yīng)了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.整個(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ù)...

?

猜你喜歡

  • 風(fēng)機(jī)的基本性能參數(shù)有哪些 低壓風(fēng)機(jī)的性能以及性能要求有哪些?

    低壓風(fēng)機(jī)的性能主要就是節(jié)能,對(duì)于我國(guó)低壓風(fēng)機(jī)性能的分析對(duì)比,在運(yùn)行的經(jīng)濟(jì)性方面與以前的低壓風(fēng)機(jī)沒有什么區(qū)別,也沒有多少起伏性,而相對(duì)于低壓風(fēng)機(jī)的性能來(lái)說,就具有非常大的發(fā)展以及創(chuàng)新,比如在送風(fēng)的距離,比如在風(fēng)量的變化幅度,比如在技術(shù)的發(fā)展?fàn)?/p>

  • 高壓離心鼓風(fēng)機(jī)的參數(shù)有哪些 高壓離心鼓風(fēng)機(jī)的參數(shù)

    參數(shù)是很多機(jī)械設(shè)置或維修上能用到的一個(gè)選項(xiàng),字面上理解是可供參考的數(shù)據(jù),但有時(shí)又不全是數(shù)據(jù)。對(duì)指定應(yīng)用而言,高壓風(fēng)機(jī)廠家可以是賦予的常數(shù)值;在泛指時(shí),它可以是一種變量,用來(lái)控制隨其變化而變化的其他的量。簡(jiǎn)單說,參數(shù)是給我們參考的。那么高壓風(fēng)

  • 高壓風(fēng)機(jī)參數(shù) 標(biāo)準(zhǔn)規(guī)格高壓風(fēng)機(jī)的選擇可以從哪些方面入手

    與其它機(jī)械零件相比,高壓旋渦風(fēng)機(jī)的規(guī)格種類較多,品種較多,因此客戶在選擇產(chǎn)品類型時(shí)會(huì)比較苦惱,因此建議客戶選擇合適的高壓風(fēng)機(jī),可以直接將各種配置配置成可供客戶使用的高壓風(fēng)機(jī)。那標(biāo)準(zhǔn)規(guī)格的高壓風(fēng)機(jī)可以從哪些方面著手?一、選擇承軸型號(hào)通用。標(biāo)準(zhǔn)

  • wq系列潛水排污泵型號(hào)_WQ潛水排污泵型號(hào)參數(shù)及含義

    潛污泵從字面上就能理解是潛水式的污水泵,常見的就是WQ型潛水排污泵,全稱是WQ潛水式高效無(wú)堵塞排污泵。這里給大家做一些型號(hào)含義。一、型號(hào)參數(shù)及含義。Q:潛水W:排污G:管道Y:自吸L:垂直P:不銹鋼B:防爆JY:攪勻像JYWQ

  • 化工泵型號(hào)參數(shù)的意義和作用_化工泵型號(hào)參數(shù)的意義

    目前,國(guó)內(nèi)廠家生產(chǎn)的化工泵主要包括:dkzb型不銹鋼撓性泵,dby型電動(dòng)隔膜泵,hkzb滑片泵,IH型化工泵,IHF型氟塑料化工泵,F(xiàn)SB型氟塑料化工泵,CQB化學(xué)磁力泵,IMD化工磁力泵,F(xiàn)ZB化工自吸泵等。這些化工泵被廣使用在化工、冶金

  • 如何選擇消防泵的參數(shù)_怎樣選擇消防泵?

    消防泵是消防設(shè)施中經(jīng)常使用和必不可少的組件。消防泵的正常運(yùn)行在滅火過程中起著決定性的作用。那么,怎樣選擇消防泵?以下是給大家簡(jiǎn)要介紹選擇消防泵的知識(shí)。要查看消防泵是否通過了我國(guó)強(qiáng)制檢查,有必要查看由消防產(chǎn)品合格評(píng)定中心發(fā)布的近一年的強(qiáng)制檢查