Swag
Swag将Go的注释转换为Swagger2.0文档。许多知名的Web框架都有对应的插件，方便快速集成。
1 获取Swag
使用如下命令下载swag：
go install github.com/swaggo/swag/cmd/swag@latest在包含
main.go文件的项目根目录运行swag init。这将会解析注释并生成需要的文件（docs文件夹和docs/docs.go）。
swag init(可选) 使用
fmt格式化 SWAG 注释。(请先升级到最新版本)
swag fmt2 Swag命令使用
swag init -h
NAME:
swag init - Create docs.go
USAGE:
swag init [command options] [arguments...]
OPTIONS:
--generalInfo value, -g value API通用信息所在的go源文件路径，如果是相对路径则基于API解析目录 (默认: "main.go")
--dir value, -d value API解析目录 (默认: "./")
--exclude value 解析扫描时排除的目录，多个目录可用逗号分隔（默认：空）
--propertyStrategy value, -p value 结构体字段命名规则，三种：snakecase,camelcase,pascalcase (默认: "camelcase")
--output value, -o value 文件(swagger.json, swagger.yaml and doc.go)输出目录 (默认: "./docs")
--parseVendor 是否解析vendor目录里的go源文件，默认不
--parseDependency 是否解析依赖目录中的go源文件，默认不
--parseDependencyLevel, --pdl 对'--parseDependency'参数进行增强, 是否解析依赖目录中的go源文件, 0 不解析, 1 只解析对象模型, 2 只解析API, 3 对象模型和API都解析 (default: 0)
--markdownFiles value, --md value 指定API的描述信息所使用的markdown文件所在的目录
--generatedTime 是否输出时间到输出文件docs.go的顶部，默认是
--codeExampleFiles value, --cef value 解析包含用于 x-codeSamples 扩展的代码示例文件的文件夹，默认禁用
--parseInternal 解析 internal 包中的go文件，默认禁用
--parseDepth value 依赖解析深度 (默认: 100)
--instanceName value 设置文档实例名 (默认: "swagger")swag fmt -h
NAME:
swag fmt - format swag comments
USAGE:
swag fmt [command options] [arguments...]
OPTIONS:
--dir value, -d value API解析目录 (默认: "./")
--exclude value 解析扫描时排除的目录，多个目录可用逗号分隔（默认：空）
--generalInfo value, -g value API通用信息所在的go源文件路径，如果是相对路径则基于API解析目录 (默认: "main.go")
--help, -h show help (default: false)3 与gin集成
使用
swag init生成Swagger2.0文档后，导入如下代码包：
import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed files可以动态设置一些通用的API信息。生成的代码包
docs导出SwaggerInfo变量，使用该变量可以通过编码的方式设置标题、描述、版本、主机和基础路径。使用Gin的示例：
package main
import (
"github.com/gin-gonic/gin"
"github.com/swaggo/files"
"github.com/swaggo/gin-swagger"
"./docs" // docs is generated by Swag CLI, you have to import it.
)
// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
func main() {
// programatically set swagger info
docs.SwaggerInfo.Title = "Swagger Example API"
docs.SwaggerInfo.Description = "This is a sample server Petstore server."
docs.SwaggerInfo.Version = "1.0"
docs.SwaggerInfo.Host = "petstore.swagger.io"
docs.SwaggerInfo.BasePath = "/v2"
docs.SwaggerInfo.Schemes = []string{"http", "https"}
r := gin.New()
// use ginSwagger middleware to serve the API docs
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
r.Run()
}每次执行增加API操作后执行以下命令生成对应文档
swag init运行程序，然后在浏览器中访问 http://localhost:8080/swagger/index.html 。将看到Swagger 2.0 Api文档
4 声明式注释格式
4.1 通用API信息
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.description
标签的外部文档说明。
// @tag.docs.description Best example documentation
contact.name
公开的API的联系信息。
// @contact.name API Support
license.name
必填 用于API的许可证名称。
// @license.name Apache 2.0
host
运行API的主机（主机名或IP地址）。
// @host localhost:8080
BasePath
运行API的基本路径。
// @BasePath /api/v1
accept
API 可以使用的 MIME 类型列表。 请注意，Accept 仅影响具有请求正文的操作，例如 POST、PUT 和 PATCH。 值必须如“Mime类型”中所述。
// @accept 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"}
4.1.1 使用Markdown描述
如果文档中的短字符串不足以完整表达，或者需要展示图片，代码示例等类似的内容，则可能需要使用Markdown描述。要使用Markdown描述，请使用一下注释。
title
必填 应用程序的名称。
// @title Swagger Example API
version
必填 提供应用程序API的版本。
// @version 1.0
description.markdown
应用程序的简短描述。 从api.md文件中解析。 这是@description的替代用法。
// @description.markdown No value needed, this parses the description from api.md
tag.name
标签的名称。
// @tag.name This is the name of the tag
tag.description.markdown
标签说明，这是tag.description的替代用法。 该描述将从名为tagname.md的文件中读取。
// @tag.description.markdown
4.2 API操作
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]
deprecatedrouter
与router相同，但是是deprecated的。
x-name
扩展字段必须以x-开头，并且只能使用json值。
deprecated
将当前API操作的所有路径设置为deprecated
4.3 Mime类型
swag 接受所有格式正确的MIME类型, 即使匹配 */*。除此之外，swag还接受某些MIME类型的别名，如下所示：
json
application/json
xml
text/xml
plain
text/plain
html
text/html
mpfd
multipart/form-data
x-www-form-urlencoded
application/x-www-form-urlencoded
json-api
application/vnd.api+json
json-stream
application/x-json-stream
octet-stream
application/octet-stream
png
image/png
jpeg
image/jpeg
gif
image/gif
4.4 参数类型
query
path
header
body
formData
4.5 数据类型
string (string)
integer (int, uint, uint32, uint64)
number (float32)
boolean (bool)
user defined struct
4.6 安全性
securitydefinitions.oauth2.application
OAuth2 application auth.
tokenUrl, scope
// @securitydefinitions.oauth2.application OAuth2Application
securitydefinitions.oauth2.implicit
OAuth2 implicit auth.
authorizationUrl, scope
// @securitydefinitions.oauth2.implicit OAuth2Implicit
securitydefinitions.oauth2.password
OAuth2 password auth.
tokenUrl, scope
// @securitydefinitions.oauth2.password OAuth2Password
securitydefinitions.oauth2.accessCode
OAuth2 access code auth.
tokenUrl, authorizationUrl, scope
// @securitydefinitions.oauth2.accessCode OAuth2AccessCode
in
// @in header
name
// @name Authorization
tokenUrl
// @tokenUrl https://example.com/oauth/token
authorizationurl
// @authorizationurl https://example.com/oauth/authorize
scope.hoge
// @scope.write Grants write access
4.7 属性
// @Param enumstring query string false "string enums" Enums(A, B, C)
// @Param enumint query int false "int enums" Enums(1, 2, 3)
// @Param enumnumber query number false "int enums" Enums(1.1, 1.2, 1.3)
// @Param string query string false "string valid" minlength(5) maxlength(10)
// @Param int query int false "int valid" minimum(1) maximum(10)
// @Param default query string false "string default" default(A)
// @Param collection query []string false "string collection" collectionFormat(multi)
// @Param extensions query []string false "string collection" extensions(x-example=test,x-nullable)也适用于结构体字段：
type Foo struct {
Bar string `minLength:"4" maxLength:"16"`
Baz int `minimum:"10" maximum:"20" default:"15"`
Qux []string `enums:"foo,bar,baz"`
}4.7.1 当前可用的
default
*
声明如果未提供任何参数，则服务器将使用的默认参数值，例如，如果请求中的客户端未提供该参数，则用于控制每页结果数的“计数”可能默认为100。 （注意：“default”对于必需的参数没有意义）。参看 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2。 与JSON模式不同，此值务必符合此参数的定义类型。
collectionFormat
string
指定query数组参数的格式。 可能的值为：
- csv - 逗号分隔值 foo,bar.
- ssv - 空格分隔值 foo bar.
- tsv - 制表符分隔值 foo\tbar.
- pipes - 管道符分隔值 foo|bar.
- multi - 对应于多个参数实例，而不是单个实例 foo=bar＆foo=baz 的多个值。这仅对“query”或“formData”中的参数有效。
默认值是 csv。
4.7.2 进一步的
uniqueItems
boolean
5 示例
package main
import (
_ "awesomeProject2/docs" // 在定义通用API信息时必须导入
"github.com/gin-gonic/gin"
swaggerFiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger" // 以上两个包只需要在定义swag路由时需要导入
)
// @title API 文档示例
// @version 1.0
// @description 这是示例 API 文档
// @host 127.0.0.1:8080 //域名不一样会导致跨域
// @BasePath
func main() {
r := gin.Default()
//config := cors.DefaultConfig()
//config.AllowOrigins = []string{"*"} //r.Use(cors.New(config)) r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
r.GET("/t", getc)
r.Run()
}
// @summary yaushdiaydi
// @success 200 {string} json ok
// @router /t [get]
func getc(c *gin.Context) {
c.JSON(200, gin.H{
"msg": "yes",
})
}在设置通用API信息时，需要导入
_ "awesomeProject2/docs"出现页面无法找到API信息时，可以使用
get -u更新一下依赖Swagger注释信息可以大写开头，也可以小写
最后更新于