好久没有给别人写接口了，正好遇到一个前后端合作的项目，是时候尝试一下 golang swagger 的 API 文档生成工具了。
注意：尝试了 swaggo 之后，感觉很不好(注释规范口味太重，与三方库有冲突)，我觉得再试试 go-swagger。但是没想到 go-swagger 更难上手，且生成速度巨慢，无法接受，还是继续使用 swaggo。
使用 swagger 的好处
- 返回的数据结构，可以直接引用 struct 的定义：https://github.com/swaggo/swag ， 但是同时带来了问题，如果 struct 里嵌入了三方库的类型，依赖检测时会出现与 swaggo 规范冲突的注释。
- 如果自己只是写后台，用 swagger 的 ui 界面可以方便的自测。避免了交付给同事有 bug 的接口
安装 swag 工具
go install github.com/swaggo/swag/cmd/swag@latest
创建 docs.go 并生成文档
修改默认文件目录。默认 swagger 会使用 docs 目录。 但是 docs 目录已经被我用了，想换个目录作为 swagger 生成文件的目录。 可以使用 output 指定输出目录。
> swag init --output api_docs --exclude frontend
2022/08/24 13:04:29 Generate swagger docs....
2022/08/24 13:04:29 Generate general API Info, search dir:./
2022/08/24 13:04:31 create docs.go at api_docs/docs.go
2022/08/24 13:04:31 create swagger.json at api_docs/swagger.json
2022/08/24 13:04:31 create swagger.yaml at api_docs/swagger.yaml
查看生成了哪些文件
> ls api_docs/
docs.go swagger.json swagger.yaml
在没有 swagger 格式的注释时，似乎也没有生成啥有用的文档。
注意，每次修改了文档，都需要执行 swag init 命令。
跑起来
参照：
https://github.com/swaggo/gin-swagger
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files
修改 main.go，并编译。
浏览器访问：
http://localhost:8000/swagger/index.html
即可看到 API 文档。
编译后的文件大小变化
- 使用前是 21M。
- 使用后是 33M。
发布方式
swaggo 是直接 build 到二进制里的，会极大增加二进制文件的大小(参考上面的数据 21M 到 33M)，一般在生产环境不需要将 docs 编译进去。
可以利用 go 提供的条件编译来实现是否编译文档。
不适合打包到 API 服务里。
安全起见，用完后，将服务关掉。
使用 jwt token 的 API
https://github.com/swaggo/gin-swagger/issues/90
疑虑
swagger 文档会不会让代码注释过于复杂。特别是让人不适的 at 符号，感觉进入了 java 的世界。跟 golang 的小清新风格不符
params 类型：body 还是 formData
https://stackoverflow.com/questions/23118249/whats-the-difference-between-request-payload-vs-form-data-as-seen-in-chrome
body 实际上是 payload body，如果提交的是序列化后的 json 字符串，就是 body.
cannot find type definition: gorm.Model
最终解决方法：(感谢 “莫路用的扁友” 大神的反馈)
swag init --parseDependency --parseInternal --parseGoList=false --parseDepth=1
以下是纠结的过程，不看也罢。
https://github.com/swaggo/swag/issues/810
swag init --parseDependency --parseInternal
但是加个这两个参数之后，又会引出更多的三方库报错，例如：
missing required param comment parameters
原因是，三方库也用了跟 swagger 同名的注解前缀，但是格式不同，就报错了。 这点让我无法接受，我觉得尝试一下 go-swagger 来替代 swaggo。
还会有更奇葩的错误：
panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x1 addr=0x10 pc=0x85c8a8]
最好是不要在注释里关联使用了三方库的 struct，例如 gorm。struct 字段可以用纯文本描述。可以用 any 类型代替。
TODO
- antd pro API VIM Snippet 更新成 swagger 格式
- 直接开搞，先生成 docs 看看格式。是否可以直接用 nginx 发布。
- Makefile
参考
- 注释规范参考 https://github.com/swaggo/swag
- 代码参考 https://github.com/swaggo/gin-swagger
- https://www.lixueduan.com/posts/go/swagger/
- gin.BasicAuth 为生产环境 Swagger UI 文档加上密码保护
微信关注我哦 👍
我是来自山东烟台的一名开发者，有感兴趣的话题，或者软件开发需求，欢迎加微信 zhongwei 聊聊， 查看更多联系方式