一、SwaggerUI介紹

SwaggerUI是色多多在线观看视频小組在做課程作業，前後端交互需要API文檔時，我無意間發現的一個工具。借助SwaggerUI，色多多在线观看视频可以便捷的獲得類似下方的可視化圖形界麵：

之後，色多多在线观看视频便可以根據此“API文檔”進行開發。

“Swagger UI 允許任何人（無論是你的開發團隊還是最終用戶）在沒有任何實現邏輯的情況下對 API 資源進行可視化和交互。它（API文檔）通過 Swagger 定義自動生成，可視化文檔使得後端實現和客戶端消費變得更加容易。” --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 http://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的數據類型
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 - 此參數沒有具體意義，單參數是強製性的，但是推薦不同請求使用不同的參數。命名格式可采用swaggXXXReq，若不同請求該參數一樣，會出現很多bug。

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

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

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

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

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

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

12. description - 參數說明

13. type - 指定參數類型

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

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

16. responses - 說明返回類型。

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

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

// Create User request// swagger:parameters swaggCreateUserReqtype swaggCreateUserReq struct {// in:bodyBody model.User} 第一行注釋：描述此參數第二行注釋：swagger:parameters表示請求參數提示符，swaggCreateUserReq為請求的參數ID值。第三行：結構體名稱沒有必要和swagger:parameters後的參數ID值保持一致，但推薦命名相同第四行注釋：in:body或者in:query表示包含此參數的位置第五行為實際的內嵌結構
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的動態交互並沒有實現，隻是將其作為API的展示文檔，還需要進一步的學習。

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