建站
咨詢
售后
建站咨詢
新聞中心
swag工具介紹和安裝
Swag是一款可以將Go的注釋轉(zhuǎn)換為Swagger2.0格式文檔的工具，生成接口文檔用到的注釋需要按照swag要求的格式書寫。
使用go install方式下載安裝swag
$ go install github.com/swaggo/swag/cmd/swag@latest
也可以從github的release頁面下載編譯好的二進(jìn)制文件，以1.8.10版本為例：
$ wget https://github.com/swaggo/swag/releases/download/v1.8.10/swag_1.8.10_Linux_x86_64.tar.gz
$ tar zxvf swag_1.8.10_Linux_x86_64.tar.gz
$ chmod +x ./swag
$ mv swag /usr/local/bin
在包含main.go文件的項(xiàng)目根目錄運(yùn)行swag init將會(huì)解析注釋并生成文件（docs文件夾），修改對應(yīng)注釋后再次運(yùn)行swag ini即可：
swag init
使用swag fmt可以格式化SWAG注釋：
swag fmt
符合swag要求的API通用注釋寫法
在main.go的main方法添加API通用注釋
// @title idcenter API
// @version 1.0
func main() {
//...
}
更多通用注釋字段說明和示例：
|
注釋 |
說明 |
示例 |
|
title |
必填 應(yīng)用程序的名稱。 |
// @title Swagger Example API |
|
version |
必填 提供應(yīng)用程序API的版本。 |
// @version 1.0 |
|
description |
應(yīng)用程序的簡短描述。 |
// @description This is a sample server celler server. |
|
tag.name |
標(biāo)簽的名稱。 |
// @tag.name This is the name of the tag |
|
tag.description |
標(biāo)簽的描述。 |
// @tag.description Cool Description |
|
tag.docs.url |
標(biāo)簽的外部文檔的URL。 |
// @tag.docs.url ??https://example.com?? |
|
tag.docs.description |
標(biāo)簽的外部文檔說明。 |
// @tag.docs.description Best example documentation |
|
termsOfService |
API的服務(wù)條款。 |
// @termsOfService ??http://swagger.io/terms/?? |
|
contact.name |
公開的API的聯(lián)系信息。 |
// @contact.name API Support |
|
contact.url |
聯(lián)系信息的URL。 必須采用網(wǎng)址格式。 |
// @contact.url ??http://www.swagger.io/support?? |
|
contact.email |
聯(lián)系人/組織的電子郵件地址。 必須采用電子郵件地址的格式。 |
// @contact.email support@swagger.io |
|
license.name |
必填 用于API的許可證名稱。 |
// @license.name Apache 2.0 |
|
license.url |
用于API的許可證的URL。 必須采用網(wǎng)址格式。 |
// @license.url ??http://www.apache.org/licenses/LICENSE-2.0.html?? |
|
host |
運(yùn)行API的主機(jī)（主機(jī)名或IP地址）。 |
// @host localhost:8080 |
|
BasePath |
運(yùn)行API的基本路徑。 |
// @BasePath /api/v1 |
|
accept |
API 可以使用的 MIME 類型列表。 請注意，Accept 僅影響具有請求正文的操作，例如 POST、PUT 和 PATCH。 值必須如“Mime類型”中所述。 |
// @accept json |
|
produce |
API可以生成的MIME類型的列表。值必須如“Mime類型”中所述。 |
// @produce json |
|
query.collection.format |
請求URI query里數(shù)組參數(shù)的默認(rèn)格式：csv，multi，pipes，tsv，ssv。 如果未設(shè)置，則默認(rèn)為csv。 |
// @query.collection.format multi |
|
schemes |
用空格分隔的請求的傳輸協(xié)議。 |
// @schemes http https |
|
externalDocs.description |
Description of the external document. |
// @externalDocs.description OpenAPI |
|
externalDocs.url |
URL of the external document. |
// @externalDocs.url ??https://swagger.io/resources/open-api/?? |
|
x-name |
擴(kuò)展的鍵必須以x-開頭，并且只能使用json值 |
// @x-example-key {"key": "value"} |
符合swag要求的具體API注釋
在接口的handler方法中添加具體的API注釋。
// Login godoc
// @Summary 登錄
// @Schemes https
// @Description 登錄
// @Tags account
// @accept json
// @Produce json
// @Param account body param.LoginReq true "login"
// @Success 200 {object} param.JSONResult{data=param.LoginRes}
// @Router /user/login [post]
func Login(g *gin.Context) {
//...
}
參數(shù)注釋和返回注釋支持結(jié)構(gòu)體，本例中用到的結(jié)構(gòu)體在param包下面，內(nèi)容如下：
// JSONResult response body結(jié)構(gòu)
type JSONResult struct {
Code int `json:"code" binding:"required"`
Data interface{} `json:"data" binding:"required"`
Msg string `json:"msg" binding:"required"`
}
// LoginReq 登錄接口入?yún)?br>type LoginReq struct {
Email string `json:"email" binding:"required,min=6,max=50"` // 郵箱
Password string `json:"Password" binding:"required,min=8,max=15"` // 密碼
}
// LoginRes 登錄接口返回參數(shù)
type LoginRes struct {
Token json:"token"` // token
}
更多注釋字段說明：
|
注釋 |
描述 |
|
description |
操作行為的詳細(xì)說明。 |
|
description.markdown |
應(yīng)用程序的簡短描述。該描述將從名為endpointname.md的文件中讀取。 |
|
id |
用于標(biāo)識操作的唯一字符串。在所有API操作中必須唯一。 |
|
tags |
每個(gè)API操作的標(biāo)簽列表，以逗號分隔。 |
|
summary |
該操作的簡短摘要。 |
|
accept |
API 可以使用的 MIME 類型列表。 請注意，Accept 僅影響具有請求正文的操作，例如 POST、PUT 和 PATCH。 值必須如“Mime類型”中所述。 |
|
produce |
API可以生成的MIME類型的列表。值必須如“Mime類型”中所述。 |
|
param |
用空格分隔的參數(shù)。param name,param type,data type,is mandatory?,comment attribute(optional) |
|
security |
每個(gè)API操作的安全性。 |
|
success |
以空格分隔的成功響應(yīng)。return code,{param type},data type,comment |
|
failure |
以空格分隔的故障響應(yīng)。return code,{param type},data type,comment |
|
response |
與success、failure作用相同 |
|
header |
以空格分隔的頭字段。 return code,{param type},data type,comment |
|
router |
以空格分隔的路徑定義。 path,[httpMethod] |
|
x-name |
擴(kuò)展字段必須以x-開頭，并且只能使用json值。 |
生成接口文檔
按照swag要求寫好注釋后，執(zhí)行如下命令生成文檔。
swag init
會(huì)在根目錄生成docs文件夾，里面包含swagger.json,、swagger.yaml和doc.go三個(gè)文件。
當(dāng)前文章：Golang項(xiàng)目自動(dòng)生成swagger格式接口文檔方法（一）
網(wǎng)站網(wǎng)址：http://www.dlmjj.cn/article/dhigjop.html
