go-swagger 与 swaggo 对比
最终没有选择 go-swagger，还是回归了 swaggo。原因：
- go-swagger 生成文档的速度奇慢无比。我一个 20 多个文件的项目，要整整 30 秒。而 swaggo 可以 5 秒完成。
- go-swagger 上手困难。官方文档不友好，没有一个简单清晰的示例说明。
虽然 swaggo 格式规范丑一点，但是至少上手容易，可以直接干活。
这个文章做的对比相对客观一点:
https://ldej.nl/post/generating-swagger-docs-from-go/
再就是我跟上面作者的观点一致，就是这两个货其实都很丑陋，这样写代码毫无乐趣。
安装
go install github.com/go-swagger/go-swagger/cmd/swagger@latest
确认安装成功：
> swagger version
version: v0.29.0
commit: (unknown, mod sum: "h1:z3YoZtLvS1Y8TE/PCat1VypcZxM0IgKLt0NvZxQyNl8=")
生成 spec 文件
swagger generate spec -o ./api_docs/swagger.json
忽略指定目录
由于历史项目问题，与 main.go 同级放了个 js 的前端项目，在执行 generate spec 命令时，半天没有结果。 所以，我想忽略指定目录。
> swagger generate spec --help
Usage:
swagger [OPTIONS] generate spec [spec-OPTIONS]
[spec command options]
-o, --output= the file to write to
-x, --exclude= exclude packages matching pattern
--include-tag= include routes having specified tags (can be specified many times)
--exclude-tag= exclude routes having specified tags (can be specified many times)
--exclude-deps exclude all dependencies of project
例如：
swagger generate spec -o ./api_docs/swagger.json -x frontend
倒是能生成，为何依旧很慢。。。比 swaggo 慢得多。看样子是不支持这种设置。
启动 Swagger Web 服务
> swagger serve api_docs/swagger.json --no-open --port 9019
2022/08/25 14:38:12 serving docs at http://localhost:9019/docs
注意，如果你在 WSL 下或 docker 中，没有本地浏览器，就需要加上 no-open，否则会报错：
webbrowser: tried to open "http://localhost:52365/docs", no screen found
默认使用的时 Redoc 模板；也可以切换为 swagger UI 模板：
swagger serve api_docs/swagger.json --no-open --port 9019 -F swagger
配合 go generate 使用
我看有做法是，在 package name 下，加入这两行
//go:generate go run github.com/go-swagger/go-swagger/cmd/swagger@latest generate spec -o openapi.yaml
//go:generate go run github.com/go-swagger/go-swagger/cmd/swagger@latest validate openapi.yaml
非 package main 的文档都没有生成
猜测，swagger:meta 需要加在每个 package 里。但这个说不通啊。。。总不能一个 package 下所有代码文件都加上吧。。。
https://goswagger.io/use/spec.html
TODO
- [X] 清理 swaggo 代码
参考
- https://github.com/go-swagger/go-swagger
- https://goswagger.io/
- https://www.sobyte.net/post/2022-05/go-swagger/
- Building Distributed Applications in Gin - Writing the OpenAPI Specification
- https://www.bacancytechnology.com/blog/create-golang-api-documentation-using-go-swagger
微信关注我哦 👍
我是来自山东烟台的一名开发者，有感兴趣的话题，或者软件开发需求，欢迎加微信 zhongwei 聊聊， 查看更多联系方式