使用 go-swagger 为 go API 自动生成文档

date

Mar 9, 2023

slug

generate-api-doc-automatic-by-go-swagger

status

Published

工欲善其事，必先利其器，这里我是在 Mac 上，通过下面的命令安装的：

执行完成之后，我发现我的 ~/go/bin 目录下有一个可执行文件 swag 。执行：

会返回：

这表示安装成功了。

但我在项目下执行：

时，却返回了：

我在 ~/.zshrc 文件下加入了如下内容：

再导入：

再次执行 swag init ，得到了如下错误：

在项目中添加 main.go 文件，再次执行命令：swag init ，发现自动生成了 docs 文件夹，文件夹下分别有 docs.go 、swagger.json 和 swagger.yaml 文件。

这说明 swag 安装成功且可以正常使用了，接下来配置命令，将文档自动导入至 yapi 中。

通过

全局安装 yapi 命令，安装成功后执行：

得到如下结果：

说明安装成功了。

上面的内容其实只做了两件事：

接下来，为了通过执行

自动生成文档，还要配置相关内容。

根据官方文档，需要进行如下配置：

其中，swag-config.go 中的内容如下：

为了将生成后的文档导入 yapi ，还需要创建并配置 yapi-import.json 。

不同项目有不同的需求，我在项目中最常用的，有两种使用方式，分别用于处理 GET 和 POST 请求：

更多使用方式，可以参考官方文档。