一、SwaggerUI介紹

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

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

“Swagger UI 允許任何人（無論是你的開發(fā)團(tuán)隊(duì)還是最終用戶）在沒有任何實(shí)現(xiàn)邏輯的情況下對 API 資源進(jìn)行可視化和交互。它（API文檔）通過 Swagger 定義自動生成，可視化文檔使得后端實(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版本號
5. License - 許可證
6. Consumes、Produces - 表示request和response的數(shù)據(jù)類型
7. Security - 授權(quán)按鈕
8. SecurityDefinitions - 安全類型定義
點(diǎn)擊Authorize會彈出如下提示框：其中即為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è)請求操作

2. PUT - HTTP方法

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

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

5. swaggPutReq - 此參數(shù)沒有具體意義，單參數(shù)是強(qiáng)制性的，但是推薦不同請求使用不同的參數(shù)。命名格式可采用swaggXXXReq，若不同請求該參數(shù)一樣，會出現(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表示成功的請求；"$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ù)類型的一個(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來表示失敗的請求。返回格式說明與上述過程一致。

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 - 提示符，表示一個(gè)請求操作
2. POST - HTTP方法
3. /api/users - 路徑
4. users - 類似于路由分隔標(biāo)簽，將相同的分隔標(biāo)簽的請求歸到同一組
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值。第三行：結(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è)句號.之前的是標(biāo)題，如果沒有句號，則這些注釋會被作為描述
7. If the user’s id is “exists”…… - 描述，在第一個(gè)句號后面的為描述
8. responses - 說明返回類型。
9. 200: swaggNoReturnValue - 簡寫，表明200返回值為swaggNoReturnValue
10. 400: swaggBadReq - 簡寫，表示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)} 啟動服務(wù)器
在項(xiàng)目根目錄下：go run swagger/swaggerui/main.go 四、效果圖

打開瀏覽器localhost:8000/swaggerui/


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

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