gin项目中集成swagger生成接口文档

Swagger

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器。

简单的来说，swagger是一款可以根据resutful风格生成的接口开发文档，并且支持做测试的一款中间软件。

一、下载安装

在你gin项目中下载安装swag

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

需要注意的是，在Go 1.17以后版本开始，go get不推荐使用安装可执行文件。所以Go 1.17以后版本可以使用 go install

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

然后下载gin-swagger

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

二、使用

1、在项目的main函数上添加如下的注释

// @title gvb_server API文档     //这个是生成的文档的标题
// @version 1.0				    //文档自定义版本
// @description API文档         //详情
// @host 127.0.0.01:8080       //端口号
// @BasePath /                //基本路径

2、在命令行中执行 swag init命令，这时候就可以看到项目中生成的docs文件了

在这里插入图片描述

3、然后在main函数中导入刚刚生成的docs包，swag init生成后的路径

在这里插入图片描述

然后就可以在我们编写的api接口上配置参数生成我们的swagger文档了

扫描二维码关注公众号，回复： 15997080 查看本文章

4、接口配置参数

在这里插入图片描述

大部分参数含义：

// @Tags        每个API操作的标记列表，以逗号分隔。
// @Summary     一个简短的操作总结。
// @Description  操作行为的详细解释。
// @Param data query SettingsUri	false	以空格分隔的参数。
// @Router /api/settings/:name [put] 用空格分隔的路径定义。路径,[httpMethod]
// @Produce json  api可以生成的MIME类型列表。值必须与Mime类型中描述的一致。
// @Success 200 {object} res.Response{data=string} 以空格分隔的成功响应。返回代码或默认值，{参数类型}，数据类型，注释

请添加图片描述
更具体参数详见：官方文档

5、访问

接口注释参数配置完成后，再执行swag init ，接下来就可以看到有api测试的swagger文档了。

访问： http://localhost:8080/swagger/index.html

注意：记得启动你的项目

在这里插入图片描述

配置完成