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

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

一、SwaggerUI介紹

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

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

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

源碼地址在這里。

二、SwaggerUI使用

user服務為例。

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

以下內容放在項目程序入口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 - 項目名稱
2. This documentation …… - 第二行為description
3. Schemes - HTTP或HTTPS
4. Version - API版本號
5. License - 許可證
6. Consumes、Produces - 表示request和response的數(shù)據(jù)類型
7. Security - 授權按鈕
8. SecurityDefinitions - 安全類型定義
點擊Authorize會彈出如下提示框:其中即為JWT認證的相關信息

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 - 提示符,表示一個請求操作

2. PUT - HTTP方法

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

4. users - 類似于路由分隔標簽,將相同的分隔標簽的請求歸到同一組

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

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

7. summary - 標題,API的概括描述

8. description - 描述,API的詳細描述

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

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

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

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

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

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

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

16. responses - 說明返回類型。

17. “200” - 200表示狀態(tài)碼,我用200表示成功的請求;"$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"`}} 第一行注釋:盡量書寫,會體現(xiàn)在swaggerui中第二行注釋:swagger:response為提示符,swaggNoReturnValue為下方數(shù)據(jù)類型的一個tag,這兩者共同組成了**"$ref": “#/responses/swaggNoReturnValue”**數(shù)據(jù)結構中,有三個屬性:Status、Errinfo、Data,上述結構中沒有返回值,所以取消了最后一個參數(shù)。

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

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

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

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

三、運行SwaggerUI

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

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

修改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)} 啟動服務器
在項目根目錄下:go run swagger/swaggerui/main.go 四、效果圖

打開瀏覽器localhost:8000/swaggerui/


swaggerui的動態(tài)交互并沒有實現(xiàn),只是將其作為API的展示文檔,還需要進一步的學習。

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

猜你喜歡

  • 背壓閥定義,背壓閥選型的4個要素

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

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

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

  • 高壓離心鼓風機的參數(shù)有哪些 高壓離心鼓風機的參數(shù)

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

  • 高壓風機參數(shù) 標準規(guī)格高壓風機的選擇可以從哪些方面入手

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

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

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

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

    被輸送液體汽化時的壓力稱為汽化壓力(飽和蒸汽壓力),液體汽化壓力的大小一般和溫度有關,溫度越高,由于液體分子運動更劇烈,其汽化壓力越大。20℃清水的汽化壓力為233.8Pa,而100℃水的汽化壓力為101296Pa(一個大氣壓)??梢?,一定

18932453205