1. 将注释添加到API源代码中,请参阅声明性注释格式。
  2. 使用如下命令下载swag:
$ go get -u github.com/swaggo/swag/cmd/swag

# 1.16 及以上版本
$ go install github.com/swaggo/swag/cmd/swag@latest

从源码开始构建的话,需要有Go环境(1.14及以上版本)。

或者从github的release页面下载预编译好的二进制文件。

  1. 在包含main.go文件的项目根目录运行swag init。这将会解析注释并生成需要的文件(docs文件夹和docs/docs.go)。
swag init

确保导入了生成的docs/docs.go文件,这样特定的配置文件才会被初始化。如果通用API指数没有写在main.go中,可以使用-g标识符来告知swag。

swag init -g http/api.go
  1. (可选) 使用fmt格式化 SWAG 注释。(请先升级到最新版本)
swag fmt

swag cli

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源文件,默认不
   --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)
最后编辑: kuteng  文档更新时间: 2022-01-19 11:54   作者:kuteng