Golang項目自動生成swagger格式接口文檔方法（一）

作者：路多辛 2023-03-06 08:53:13

Swag是一款可以將Go的注釋轉換為Swagger2.0格式文檔的工具，生成接口文檔用到的注釋需要按照swag要求的格式書寫。

swag工具介紹和安裝

Swag是一款可以將Go的注釋轉換為Swagger2.0格式文檔的工具，生成接口文檔用到的注釋需要按照swag要求的格式書寫。

使用go install方式下載安裝swag

$ go install github.com/swaggo/swag/cmd/swag@latest

也可以從github的release頁面下載編譯好的二進制文件，以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文件的項目根目錄運行swag init將會解析注釋并生成文件（docs文件夾），修改對應注釋后再次運行swag ini即可：

swag init

使用swag fmt可以格式化SWAG注釋：

swag fmt

符合swag要求的API通用注釋寫法

在main.go的main方法添加API通用注釋

// @title         idcenter API
// @version       1.0
func main() {
  //...
}

更多通用注釋字段說明和示例：

注釋	說明	示例
title	必填應用程序的名稱。	// @title Swagger Example API
version	必填提供應用程序API的版本。	// @version 1.0
description	應用程序的簡短描述。	// @description This is a sample server celler server.
tag.name	標簽的名稱。	// @tag.name This is the name of the tag
tag.description	標簽的描述。	// @tag.description Cool Description
tag.docs.url	標簽的外部文檔的URL。	// @tag.docs.url ??https://example.com??
tag.docs.description	標簽的外部文檔說明。	// @tag.docs.description Best example documentation
termsOfService	API的服務條款。	// @termsOfService ??http://swagger.io/terms/??
contact.name	公開的API的聯系信息。	// @contact.name API Support
contact.url	聯系信息的URL。必須采用網址格式。	// @contact.url ??http://www.swagger.io/support??
contact.email	聯系人/組織的電子郵件地址。必須采用電子郵件地址的格式。	// @contact.email support@swagger.io
license.name	必填用于API的許可證名稱。	// @license.name Apache 2.0
license.url	用于API的許可證的URL。必須采用網址格式。	// @license.url ??http://www.apache.org/licenses/LICENSE-2.0.html??
host	運行API的主機（主機名或IP地址）。	// @host localhost:8080
BasePath	運行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里數組參數的默認格式：csv，multi，pipes，tsv，ssv。如果未設置，則默認為csv。	// @query.collection.format multi
schemes	用空格分隔的請求的傳輸協議。	// @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	擴展的鍵必須以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) {
  //...
}

參數注釋和返回注釋支持結構體，本例中用到的結構體在param包下面，內容如下：

// JSONResult response body結構
type JSONResult struct {
  Code int         `json:"code" binding:"required"`
  Data interface{} `json:"data" binding:"required"`
  Msg  string      `json:"msg" binding:"required"`
}

// LoginReq 登錄接口入參
type LoginReq struct {
  Email     string  `json:"email" binding:"required,min=6,max=50"`     // 郵箱
  Password  string  `json:"Password" binding:"required,min=8,max=15"`  // 密碼
}

// LoginRes 登錄接口返回參數
type LoginRes struct {
   Token json:"token"` // token
}

更多注釋字段說明：

注釋	描述
description	操作行為的詳細說明。
description.markdown	應用程序的簡短描述。該描述將從名為endpointname.md的文件中讀取。
id	用于標識操作的唯一字符串。在所有API操作中必須唯一。
tags	每個API操作的標簽列表，以逗號分隔。
summary	該操作的簡短摘要。
accept	API 可以使用的 MIME 類型列表。請注意，Accept 僅影響具有請求正文的操作，例如 POST、PUT 和 PATCH。值必須如“Mime類型”中所述。
produce	API可以生成的MIME類型的列表。值必須如“Mime類型”中所述。
param	用空格分隔的參數。param name,param type,data type,is mandatory?,comment attribute(optional)
security	每個API操作的安全性。
success	以空格分隔的成功響應。return code,{param type},data type,comment
failure	以空格分隔的故障響應。return code,{param type},data type,comment
response	與success、failure作用相同
header	以空格分隔的頭字段。 return code,{param type},data type,comment
router	以空格分隔的路徑定義。 path,[httpMethod]
x-name	擴展字段必須以x-開頭，并且只能使用json值。

生成接口文檔

按照swag要求寫好注釋后，執行如下命令生成文檔。

swag init

會在根目錄生成docs文件夾，里面包含swagger.json,、swagger.yaml和doc.go三個文件。

責任編輯：姜華來源：今日頭條

Swag 工具