go-swagger 生成 API 文档，及与 swaggo 的对比

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

tags: swagger

关于作者 🌱

我是来自山东烟台的一名开发者，有敢兴趣的话题，或者软件开发需求，欢迎加微信 zhongwei 聊聊， 查看更多联系方式