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

发布时间: 2022-08-26 08:45:14 作者: 大象笔记

go-swagger 与 swaggo 对比

最终没有选择 go-swagger,还是回归了 swaggo。原因:

虽然 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

参考

我是一名山东烟台的开发者,联系作者