使用swaggo自动生成Restful API文档

最新推荐文章于 2024-09-17 17:26:52 发布

一叶知秋@qqy

最新推荐文章于 2024-09-17 17:26:52 发布

阅读量782

点赞数

文章标签： swaggo

本文链接：https://blog.csdn.net/qq_41004932/article/details/120157640

版权

本文介绍了如何在Mac环境下使用Swaggo为Go Gin应用自动生成Swagger API文档。Swaggo简化了Swagger YAML的编写，通过注释转化成文档。文章详细阐述了安装、配置步骤以及解决可能出现的问题，展示了Swaggo如何帮助开发者快速创建和测试API接口。

摘要由CSDN通过智能技术生成

前言

本文参考了两篇优质博客，并作出最后参考整理
Swaggo - Go语言中文文档
 Mac下安装swaggo
本文是在mac环境下，但是方法在windows下是相通的，因为都是基于goland的终端进行的操作，如果是在系统终端下也是ok的。

在写代码时也是要写明注释的，而写完api接口之后，肯定也是要对外提供api文档，这样别人才能够准确使用你的借口，而好的接口文档可以为你后期减少很多不必要的沟通问题。

再者，在开发api阶段你肯定也是要自己验证api的结果的，而swaggo的出现则是让你在写代码阶段就完成了api文档的建设，而且后期无论自己测试api或者他人测试api都是可以使用的，最重要的是他还是交互式的api文档。

最后的文档是如下所示的：
在这里插入图片描述
当然了，这里仅是个小例子。

关于Swaggo

或许你使用过Swagger, 而 swaggo就是代替了你手动编写yaml的部分。只要通过一个命令就可以将注释转换成文档，这让我们可以更加专注于代码。

目前swaggo主要实现了swagger 2.0 的以下部分功能：

基本结构（Basic Structure）
API 地址与基本路径（API Host and Base Path）
路径与操作（Paths and Operations）
参数描述（Describing Parameters）
请求参数描述（Describing Request Body）
返回描述（Describing Responses）
MIME 类型（MIME Types）
认证（Authentication）
Basic Authentication
API Keys
添加实例（Adding Examples）
文件上传（File Upload）
枚举（Enums）
按标签分组（Grouping Operations With Tags）
扩展（Swagger Extensions）

使用

安装swag cli 及下载相关包

要使用swaggo,首先需要安装swag cli。

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

然后我们还需要两个包。

// gin-swagger 中间件
go get github.com/swaggo/gin-swagger
// swagger 内置文件
go get github.com/swaggo/gin-swagger/swaggerFiles

验证安装结果

可以看一下自己安装的版本
使用如下命令：

swag --version

如果一切正常的话会出现如下结果：

swag version v1.7.1

但是估计大概率是会出现下面的错误：

zsh: command not found: swag

这是因为安装的swag并未被加进系统环境内，所以在使用时会提示找不到。
使用go env查看gopath的目录，因为安装的swag是存在GOPATH目录下的。
然后使用绝对路径使用swag：

/usr/local/GOPATH/bin/swag --version

//返回结果
swag version v1.7.1

所以只要把swag的路径加到环境变量中就可以了，这里是加到~/.zshrc文件中，其他的也是ok的。

vim ~/.zshrc

添加

export PATH="/usr/local/GOPATH/bin:$PATH"

路径根据自己的实际情况进行调整

展示

但是我已经写好注释了，也引用完库了，该做的都做了，依然出现问题：
在这里插入图片描述
解决方法是在router文件引入swagger生成的docs文件夹即可。即路由初始化的地方。

_ "EmbedToolServer/docs"

然后就出现了开始的界面。

测试

点击这条api
在这里插入图片描述
可以查看到api的一些信息，展示的信息是根据注释决定的。

点击Try it out

这个api是上传一个excel保存至指定目录，所以点击选择文件，选中一个excel文件。

点击Execute发起请求

可以发现swagger上已经将一些过程结果信息更新展示出来了，并且服务端也收到并打印出了这次请求，而且，已经在目录下出现了这个excel