【RESTful API 文档】为 Gin 开发项目加上 Swag 和 gin-swagger 自动生成 RESTful API 接口文档

缓缓躺下

已于 2023-09-14 15:54:31 修改

阅读量332

点赞数

分类专栏： # API 文档文章标签： gin go golang

于 2023-08-16 13:29:45 首次发布

本文链接：https://blog.youkuaiyun.com/weixin_41989013/article/details/132311294

版权

API 文档专栏收录该内容

2 篇文章

订阅专栏

本文介绍了Gin项目自动生成RESTful API文档的方法。首先要安装swag和gin - swagger依赖，包括下载、验证及解决安装问题；接着进行自动生成文档的准备工作，如给Go代码添加注释、修改路由文件；最后启动项目，在浏览器输入对应地址即可查看API文档。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

自动生成 RESTful API 文档需要先安装 swag ，然后安装 gin-swagger。

一、安装 swag 和 gin-swagger

1.下载 swag 依赖

2.验证 swag 依赖

3.解决‘swag’ 不是内部或外部命令……问题

一、安装 swag 和 gin-swagger

1.下载 swag 依赖

go get -u github.com/swaggo/swag/cmd/swag

2.验证 swag 依赖

在 cmd 窗口输入：

swag

或者

swag -v

出入命令后出现提示【‘swag’ 不是内部或外部命令，也不是可运行的程序或批处理文件】

3.解决‘swag’ 不是内部或外部命令……问题

方式一

分析问题：想要直接在 cmd 窗口使用 swag 命令？那么至少要有对应可运行的程序。

因为安装 Go 时已经配置了 PATH 和 GOPATH ，所以这时去检查 Go 的环境变量 GOPATH 中的 bin 目录下（比如：C:\Users\Vcom\go\bin）是否有 swag.exe 文件（可运行程序）。

如果没有找到 swag.exe 文件，那么在 cmd 窗口确实运行不了 swag 程序。

解决方法：需要进入GOPATH 中的 pkg 目录，点击 mod 文件夹，接下来按照刚才下载依赖的路径 github.com/swaggo/swag/cmd/swag 找到 “swag”文件夹（比如：C:\Users\Vcom\go\pkg\mod\github.com\swaggo\swag@v1.16.1\cmd\swag）。

在找到的 swag 文件夹中可以看到 main.go 文件，接着在此目录下打开 cmd 窗口。

接下来在 cmd 窗口中输入 go build 回车后等待即可。

go build 之后会生成 swag.exe 文件

最后把 swag.exe 文件复制到 GOPATH 中的 bin 目录下（比如：C:\Users\Vcom\go\bin）就可以重新验证 swag 依赖了。

方式二

官方给的解决方法

分析原因：从Go 1.17开始，不支持使用Go get安装可执行文件。

解决问题：可以使用 Go install （注：@latest 表示安装最新的）

go install github.com/swaggo/swag/cmd/swag@latest

代替

go get -u github.com/swaggo/swag/cmd/swag

下面开始重新验证 swag ~~

4.再次验证 swag 是否安装成功

验证的过程就是检查 GOPATH 的 bin 目录下是否有 swag 文件，因为 swag 文件（可运行程序）会对 swag 命令或 swag -v 命令有对应的回应。

如果这个时候在你的 Go 项目根路径下(例如~/Go -project-name)运行 swag init 命令， swag将解析注释并在~/ Go -project-name/docs下生成所需的文件(docs文件夹和docs/doc.go)，见下图红色框：

（可以前往 github 深入学习 Swag：https://github.com/swaggo/swag/blob/master/README_zh-CN.md）

个人建议学习完下面的内容后，再深入探究 swag init 命令生成的文件。

在项目中生成 API 文档，还需要继续安装第三方依赖。以 gin 项目为例，继续安装第三方依赖~

5.下载 gin-swagger 依赖

上面安装的 swag 依赖是生成 swagger2.0 文档，现在安装 gin-swagger 依赖，它使用 swagger 2.0自动生成 RESTful API 文档。

下载gin-swagger:：

go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

gin-swagger 的验证可以在项目的根目录下使用 swag init 命令。放在后面验证，这里省略……

二、自动生成文档的准备工作

1.给 go 代码添加注释

代码添加注释，示例如下所示：

// @BasePath /api/v1

// PingExample godoc
// @Summary ping example
// @Schemes
// @Description do ping
// @Tags example
// @Accept json
// @Produce json
// @Success 200 {string} Helloworld
// @Router /example/helloworld [get]
func Helloworld(g *gin.Context)  {
	g.JSON(http.StatusOK,"helloworld")
}

添加注释最好参考官方文档：

https://github.com/swaggo/swag/blob/master/README_zh-CN.md

mirrors / swaggo / gin-swagger · GitCode

添加注释后，在项目根目录的命令窗口输入 swag init 命令生成一个文档，生成的文档将存储在项目的 docs/ 目录下。

2.修改路由文件

使用 swag init 命令生成一个文档后，文档将存储在docs/目录下。

想要在浏览器中使用文档，需要导入包

import (
   "github.com/gin-gonic/gin"
   docs "demo/docs"   // 导入 demo 项目下 docs 这个包，并且起个别名叫 docs
   swaggerfiles "github.com/swaggo/files"  // 导入包后起别名 swaggerfiles      
   ginSwagger "github.com/swaggo/gin-swagger"  // 导入包后起别名 ginSwagger 
   "net/http"
)

上面导入了4个包，第1个是 gin 包，使用 gin 框架时自动导入的；

第2-4个是 gin-swagger 的包，这里手动导入，并起别名。

导入包之后，使用包，在路由中添加代码：

// docs ginSwagger swaggerfiles 是包的别名
docs.SwaggerInfo.BasePath = "/api/v1"   
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))

这两行代码个人理解：

docs.SwaggerInfo.BasePath 是设置接口基本路径

r.GET("/swagger/*any",ginSwagger.WrapHandler(swaggerfiles.Handler)) 是设置访问API文档的路由和调用的处理器函数。

3.查看 API 文档

查看 API 文档之前，回顾一下：先安装了依赖，并且已经给接口函数添加过注释、导入相关包（一般在路由所在的文件中导入）、运行 swag init 命令，启动项目即可查看 API 文档（启动项目前要确保使用了 swag init 命令）。

运行项目之后，在浏览器输入：http://localhost:8000/swagger/index.html ，可以看到 Swagger UI（API 文档）。（注：这里的 8000 是服务的端口，请根据自己的项目修改）

Gin 项目自动生成 API 文档必看的 gin-swagger 地址：https://github.com/swaggo/gin-swagger