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

更新日期: 2022-08-26 阅读次数: 439 字数: 579 分类: golang

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

爱评论不评论