swagger

大象笔记 > 标签 > swagger

使用 swaggo 及 gin-swagger 生成 API 文档

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

阅读全文...

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/ 再就是我跟上面作者的观点一致,就是这两个货其实都很丑陋,这样 ...

阅读全文...

gin.BasicAuth 为生产环境 Swagger UI 文档加上密码保护

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

阅读全文...