gin swagger 可能遇到的错误

gin swagger 可能遇到的错误

1. 生成的 swagger.json 为空

https://github.com/swaggo/swag

https://github.com/swaggo/gin-swagger

这两个项目可以根据注释来生成 swagger 文档。具体如何生成的，看一下项目文档就能明白。

执行 swag init 时会生成一个 doc 目录里面包含 doc.go、swagger.json、swagger.yaml

如果你的项目目录是这样的

├── cmd
│   ├── main.go
│   └── server
├── docs
│   ├── docs.go
│   ├── swagger.json
│   └── swagger.yaml
└── internal
    ├── server
    │   ├── grpc.go
    │   ├── http.go

如果你的项目目录大概是这个样子的。main.go 没有在项目根目录下，internal/server/http.go 是你的"注释"存放的位置。然后你在 cmd 目录下执行 swag init --output ../docs 是没有办法生成你想要的内容的。

因为执行 swag init 时，会在当前目录下搜索注释内容并生成 swagger.json 文档。

所以：你可以在 cmd 和 internal 的上层目录执行：

swag init -g ./cmd/main.go

默认会在cmd 同级目录生成出来 docs 文档目录

看一下 swag init 的参数

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解析目录 (默认: "./")
   --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的顶部，默认是

也就是说，如果你没有通过 -g 指定 main.go 的位置，则默认查找当前目录。如果你没有通过 -o 指定 docs 的生成位置，则默认是当前目录。