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

一、SwaggerUI介紹

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

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

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

源碼地址在這里。

二、SwaggerUI使用

以user服務(wù)為例。

安裝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 - 項目名稱(chēng)
2. This documentation …… - 第二行為description
3. Schemes - HTTP或HTTPS
4. Version - API版本號
5. License - 許可證
6. Consumes、Produces - 表示request和response的數據類(lèi)型
7. Security - 授權按鈕
8. SecurityDefinitions - 安全類(lèi)型定義
點(diǎn)擊Authorize會(huì )彈出如下提示框：其中即為JWT認證的相關(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è)請求操作

2. PUT - HTTP方法

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

4. users - 類(lèi)似于路由分隔標簽，將相同的分隔標簽的請求歸到同一組

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

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

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

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

9. parameters - URL參數，此例子中為{userId}，如果需要query的，可使用？name={name}來(lái)表示

10. - name - 指定參數，此例子中為URL中的userId

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

12. description - 參數說(shuō)明

13. type - 指定參數類(lèi)型

14. required - 是否一定需要此參數

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

16. responses - 說(shuō)明返回類(lèi)型。

17. “200” - 200表示狀態(tài)碼，我用200表示成功的請求；"$ref": "#/responses/swaggNoReturnValue"按照此格式來(lái)書(shū)寫(xiě)，其中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"`}} 第一行注釋?zhuān)罕M量書(shū)寫(xiě)，會(huì )體現在swaggerui中第二行注釋?zhuān)簊wagger:response為提示符，swaggNoReturnValue為下方數據類(lèi)型的一個(gè)tag，這兩者共同組成了**"$ref": “#/responses/swaggNoReturnValue”**數據結構中，有三個(gè)屬性：Status、Errinfo、Data，上述結構中沒(méi)有返回值，所以取消了最后一個(gè)參數。

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

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

// Create User request// swagger:parameters swaggCreateUserReqtype swaggCreateUserReq struct {// in:bodyBody model.User} 第一行注釋?zhuān)好枋龃藚档诙凶⑨專(zhuān)?strong>swagger:parameters表示請求參數提示符，swaggCreateUserReq為請求的參數ID值。第三行：結構體名稱(chēng)沒(méi)有必要和swagger:parameters后的參數ID值保持一致，但推薦命名相同第四行注釋?zhuān)篿n:body或者in:query表示包含此參數的位置第五行為實(shí)際的內嵌結構
6. Create a new user with the profile. - 摘要（標題），在第一個(gè)句號.之前的是標題，如果沒(méi)有句號，則這些注釋會(huì )被作為描述
7. If the user’s id is “exists”…… - 描述，在第一個(gè)句號后面的為描述
8. responses - 說(shuō)明返回類(lèi)型。
9. 200: swaggNoReturnValue - 簡(jiǎn)寫(xiě)，表明200返回值為swaggNoReturnValue
10. 400: swaggBadReq - 簡(jiǎn)寫(xiě)，表示400返回值為swaggerBadReq

【說(shuō)明】swagger:parameters & swagger:response已在上述操作中詳細說(shuō)明，不在敘述。

三、運行SwaggerUI

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

其中dist文件夾即為克隆的項目中的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ù)器
在項目根目錄下：go run swagger/swaggerui/main.go 四、效果圖

打開(kāi)瀏覽器localhost:8000/swaggerui/


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

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