Golang项目自动生成swagger格式接口文档方法（一）-51CTO.COM

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三个文件。