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

初探的意思是什么_初探是什么意思

一、SwaggerUI介紹

SwaggerUI是我們小組在做課程作業(yè),前后端交互需要API文檔時(shí),我無意間發(fā)現(xiàn)的一個(gè)工具。借助SwaggerUI,我們可以便捷的獲得類似下方的可視化圖形界面:

之后,我們便可以根據(jù)此“API文檔”進(jìn)行開發(fā)。

“Swagger UI 允許任何人(無論是你的開發(fā)團(tuán)隊(duì)還是最終用戶)在沒有任何實(shí)現(xiàn)邏輯的情況下對(duì) API 資源進(jìn)行可視化和交互。它(API文檔)通過 Swagger 定義自動(dòng)生成,可視化文檔使得后端實(shí)現(xiàn)和客戶端消費(fèi)變得更加容易?!?--SmartBear

源碼地址在這里。

二、SwaggerUI使用

user服務(wù)為例。

安裝go-swagger $ go get github.com/go-swagger/go-swagger/cmd/swagger swagger:meta

以下內(nèi)容放在項(xiàng)目程序入口main.go中:

// Copyright 2019 money-hub. All rights reserved.// Use of this source code is governed by a MIT-style// license that can be found in the LICENSE file.// money-hub MoneyDodo/personalTasks//// This documentation describes example APIs found under https://github.com/ribice/golang-swaggerui-example//// Schemes: http// Version: 1.0.0// License: MIT http://opensource.org/licenses/MIT//// Consumes:// - application/json//// Produces:// - application/json//// Security:// - bearer//// SecurityDefinitions:// bearer:// type: apiKey// name: Authorization// in: header//// swagger:meta

1. money-hub MoneyDodo/personalTasks - 項(xiàng)目名稱
2. This documentation …… - 第二行為description
3. Schemes - HTTP或HTTPS
4. Version - API版本號(hào)
5. License - 許可證
6. Consumes、Produces - 表示request和response的數(shù)據(jù)類型
7. Security - 授權(quán)按鈕
8. SecurityDefinitions - 安全類型定義
點(diǎn)擊Authorize會(huì)彈出如下提示框:其中即為JWT認(rèn)證的相關(guān)信息

swagger:operation // swagger:operation PUT /api/users/{userid} users swaggPutReq// ---// summary: Update the user profile// description: Update the user profile with the profile. Also, you need to specify the user ID.// parameters:// - name: userid// in: path// description: id of user// type: string// required: true// - name: Body// in: body// schema:// "$ref": "#/definitions/User"http:// required: true// responses:// "200":// "$ref": "#/responses/swaggNoReturnValue"http:// "400":// "$ref": "#/responses/swaggBadReq"

1. swagger:operation - 提示符,表示一個(gè)請(qǐng)求操作

2. PUT - HTTP方法

3. /api/users/{userid} - 路徑

4. users - 類似于路由分隔標(biāo)簽,將相同的分隔標(biāo)簽的請(qǐng)求歸到同一組

5. swaggPutReq - 此參數(shù)沒有具體意義,單參數(shù)是強(qiáng)制性的,但是推薦不同請(qǐng)求使用不同的參數(shù)。命名格式可采用swaggXXXReq,若不同請(qǐng)求該參數(shù)一樣,會(huì)出現(xiàn)很多bug。

6. — - 分隔符,下方代碼為YAML格式的swagger規(guī)范,縮進(jìn)必須保持一致且正確,推薦使用兩格縮進(jìn)。否則將無法正常解析。

7. summary - 標(biāo)題,API的概括描述

8. description - 描述,API的詳細(xì)描述

9. parameters - URL參數(shù),此例子中為{userId},如果需要query的,可使用?name={name}來表示

10. - name - 指定參數(shù),此例子中為URL中的userId

11. in - 表示此參數(shù)位于哪個(gè)部分,path表示位于URL路徑中,body表示位于上傳的request body中

12. description - 參數(shù)說明

13. type - 指定參數(shù)類型

14. required - 是否一定需要此參數(shù)

15. schema - 當(dāng)參數(shù)位于body中需要此參數(shù),指定參數(shù)的數(shù)據(jù)結(jié)構(gòu),**"$ref": “#/definitions/XXX”**按照此種格式寫即可,XXX為定義的model文件(并非swagger/model.go)中的具體的數(shù)據(jù)類型,具體原因尚未搞懂。

16. responses - 說明返回類型。

17. “200” - 200表示狀態(tài)碼,我用200表示成功的請(qǐng)求;"$ref": "#/responses/swaggNoReturnValue"按照此格式來書寫,其中swaggNoReturnValue定義在swagger/model.go文件中,使用到了swagger:response

// HTTP status code 200 and no return value// swagger:response swaggNoReturnValuetype swaggNoReturnValue struct {// in:bodyBody struct {// HTTP Status Code 200Status bool `json:"status"`// Detailed error messageErrinfo string `json:"errinfo"`}} 第一行注釋:盡量書寫,會(huì)體現(xiàn)在swaggerui中第二行注釋:swagger:response為提示符,swaggNoReturnValue為下方數(shù)據(jù)類型的一個(gè)tag,這兩者共同組成了**"$ref": “#/responses/swaggNoReturnValue”**數(shù)據(jù)結(jié)構(gòu)中,有三個(gè)屬性:Status、Errinfo、Data,上述結(jié)構(gòu)中沒有返回值,所以取消了最后一個(gè)參數(shù)。

18. “400” - 400表示狀態(tài)碼,我用400來表示失敗的請(qǐng)求。返回格式說明與上述過程一致。

swagger:route // swagger:route POST /api/users users swaggCreateUserReq// Create a new user with the profile.// If the user's id is "exists", error will be returned.// responses:// 200: swaggNoReturnValue// 400: swaggBadReq

swagger:route 是簡(jiǎn)單 API 的短注釋,它適用于沒有輸入?yún)?shù)(路徑/查詢參數(shù))的 API,如果API存在users/{userid}或者users/search?name={name}類型的參數(shù),則必須使用swagger:operation。
1. swagger:route - 提示符,表示一個(gè)請(qǐng)求操作
2. POST - HTTP方法
3. /api/users - 路徑
4. users - 類似于路由分隔標(biāo)簽,將相同的分隔標(biāo)簽的請(qǐng)求歸到同一組
5. swaggCreateUserReq - 用于請(qǐng)求上傳的參數(shù)
參數(shù)定義在swagger/model.go文件中,使用到swagger:parameters

// Create User request// swagger:parameters swaggCreateUserReqtype swaggCreateUserReq struct {// in:bodyBody model.User} 第一行注釋:描述此參數(shù)第二行注釋:swagger:parameters表示請(qǐng)求參數(shù)提示符,swaggCreateUserReq為請(qǐng)求的參數(shù)ID值。第三行:結(jié)構(gòu)體名稱沒有必要和swagger:parameters后的參數(shù)ID值保持一致,但推薦命名相同第四行注釋:in:body或者in:query表示包含此參數(shù)的位置第五行為實(shí)際的內(nèi)嵌結(jié)構(gòu)
6. Create a new user with the profile. - 摘要(標(biāo)題),在第一個(gè)句號(hào).之前的是標(biāo)題,如果沒有句號(hào),則這些注釋會(huì)被作為描述
7. If the user’s id is “exists”…… - 描述,在第一個(gè)句號(hào)后面的為描述
8. responses - 說明返回類型。
9. 200: swaggNoReturnValue - 簡(jiǎn)寫,表明200返回值為swaggNoReturnValue
10. 400: swaggBadReq - 簡(jiǎn)寫,表示400返回值為swaggerBadReq

【說明】swagger:parameters & swagger:response已在上述操作中詳細(xì)說明,不在敘述。

三、運(yùn)行SwaggerUI

從Github swagger-ui中克隆項(xiàng)目到本地,然后拷貝其中的dist文件夾到我們的項(xiàng)目文件下。

其中dist文件夾即為克隆的項(xiàng)目中的dist;model.go為我們定義的swagger:parameters和swagger:response所在的文件;main.go為swaggerui的服務(wù)器文件。

修改swagger/swaggerui/dist/index.html中的url const ui = SwaggerUIBundle({ url: "./swagger.user.json", dom_id: '#swagger-ui', ……}) 定義main.go package mainimport "net/http"func main() {fs := http.FileServer(http.Dir("swagger/swaggerui/dist"))http.Handle("/swaggerui/", http.StripPrefix("/swaggerui/", fs))http.ListenAndServe(":8000", nil)} 啟動(dòng)服務(wù)器
在項(xiàng)目根目錄下:go run swagger/swaggerui/main.go 四、效果圖

打開瀏覽器localhost:8000/swaggerui/


swaggerui的動(dòng)態(tài)交互并沒有實(shí)現(xiàn),只是將其作為API的展示文檔,還需要進(jìn)一步的學(xué)習(xí)。

參考鏈接:
https://www.ribice.ba/serving-swaggerui-golang/
https://www.ribice.ba/swagger-golang/

猜你喜歡

  • 背壓閥定義,背壓閥選型的4個(gè)要素

    背壓閥安裝在出口管道上,用于防止液體回流,背壓閥用于保持計(jì)量泵出口有一恒定壓力,為計(jì)量泵創(chuàng)造良好的工作環(huán)境并改善泵的工作性能。背壓閥選型時(shí)要注意哪些事項(xiàng)?1、所需背壓閥的口徑,一般是泵出口的管徑;2、所需設(shè)定的壓力范圍;3、需要什么材質(zhì)的,

  • 風(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ī)的性能來說,就具有非常大的發(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í),它可以是一種變量,用來控制隨其變化而變化的其他的量。簡(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潛水式高效無堵塞排污泵。這里給大家做一些型號(hào)含義。一、型號(hào)參數(shù)及含義。Q:潛水W:排污G:管道Y:自吸L:垂直P:不銹鋼B:防爆JY:攪勻像JYWQ

  • 離心泵汽蝕的定義_什么是離心泵汽蝕?

    被輸送液體汽化時(shí)的壓力稱為汽化壓力(飽和蒸汽壓力),液體汽化壓力的大小一般和溫度有關(guān),溫度越高,由于液體分子運(yùn)動(dòng)更劇烈,其汽化壓力越大。20℃清水的汽化壓力為233.8Pa,而100℃水的汽化壓力為101296Pa(一個(gè)大氣壓)。可見,一定