swagger

2023-04-27 · 阅读 9105 · 字数 903

好久没有给别人写接口了，正好遇到一个前后端合作的项目，是时候尝试一下 golang swagger 的 API 文档生成工具了。 注意：尝试了 swaggo 之后，感觉很不好(注释规范口味太重，与三方库有冲突)，我觉得再试试 go-swagger。但是没想到 go-swagger 更难上手，且生成速度巨慢，无法接受，还是继续使用 swaggo。 使用 swagger 的好处 返回的数据结构，可以直接引用 struct 的定义：https://github.com/swaggo/swag ， 但是同时带来了问题，如果 struct 里嵌入了三方库的类型，依赖检测时会出现与 swaggo 规范冲 ...

阅读全文...

2022-08-26 · 阅读 6159 · 字数 579

go-swagger 与 swaggo 对比 最终没有选择 go-swagger，还是回归了 swaggo。原因： go-swagger 生成文档的速度奇慢无比。我一个 20 多个文件的项目，要整整 30 秒。而 swaggo 可以 5 秒完成。 go-swagger 上手困难。官方文档不友好，没有一个简单清晰的示例说明。 虽然 swaggo 格式规范丑一点，但是至少上手容易，可以直接干活。 这个文章做的对比相对客观一点: https://ldej.nl/post/generating-swagger-docs-from-go/ 再就是我跟上面作者的观点一致，就是这两个货其实都很丑陋，这样 ...

阅读全文...

2022-09-01 · 阅读 3609 · 字数 312

虽然大家都推荐将 Swagger 接口文档服务部署在开发环境，但是由于现公司前后端开发人员异地办公，我还是倾向于将 swaggo 服务部署在生产环境。加上个简单的账号密码访问限制即可。 方案选型 Nginx auth golang gin auth 最终，我选择了 gin basic auth 的方案，主要是写在代码里，省去了线上一丢丢地配置麻烦。以后迁移服务器也不用太操心。 安全问题 url 中不使用 swagger 前缀，防止 swagger 出现比较大的漏洞，被人扫出漏洞。例如这里使用了 api-doc，虽然也很容易被猜出。。。还是自己想个复杂的 url 前缀比较安全。 实现代码 ...

阅读全文...

2023-04-27 · 阅读 1735 · 字数 286

这个周都在写 swaggo 接口文档，起因是要迁移一个旧的 golang gin 后台接口服务，新的系统只需要用到部分原有系统的接口。 但是，为了预防未来可能功能扩展，还是想继续保留原有系统的接口文档，不做删除处理。 那么，在用 swaggo 生成接口文档的时候，就出现了问题。如何屏蔽掉不需要的接口文档？ 看起来很简单，直接用 exclude 参数不就行了？实际测试，这个 exclude 参数只支持目录，不支持具体文件，虽然 帮助文档里写是支持具体文件，但是即便更新了最新版本的 swaggo，也是不生效。 后来发现新版本支持了 tags 来指定生成文档。这就满足需求了，而且 tag 控制精度比 ...

阅读全文...

2023-05-06 · 阅读 1846 · 字数 368

最近一直写接口文档，基于 swaggo 实现的文档服务。由于要跟前端配合，所以每天都要频繁更新接口文档，非常麻烦。之前是半自动化状态： makefile 中 scp 文档程序到服务器 手动登录服务器，再 makefile 执行 systemd reload 文档服务 (文档服务基于 golang gin 所以需要重启服务) 最近在看一个开源项目的 Makefile 时，发现可以使用 ssh 远程执行命令，这样就不需要手动登录服务器来操作了，甚好。 Makefile 代码 .PHONY: doc doc: swag init --output api_docs --tags "微 ...

阅读全文...