草庐IT

Swaggo快速上手

知奕奕 2023-04-08 原文

配置流程

注意区分

go-swagger != swaggo

二者功能差不多,都是生成接口文档用的;
前者构建速度极慢且官方文档极不友好;
后者构建速度快且上手简单,故我们这里采用它;


下载 swaggo

项目根目录下(即与 go.mod 同级的文件夹)命令行执行此代码,下载 swaggo
go get -u github.com/swaggo/swag/cmd/swag


之后就是关键的 swag 环境变量配置!

  1. 进入你之前设置的 GOPATH 目录下
  2. 进入该文件夹:pkg\mod\github.com\swaggo\swag@v1.8.9\cmd\swag,发现里面有一个文件 main.go
  3. 在当前文件夹下打开命令行,输入 go build 执行构建过程
  4. 构建完毕得到 swag.exe ,复制他
  5. 丢到 golang 根目录下的 bin 文件夹内即可(前提是你之前在系统变量 path 里面添加了%GOROOT/bin 这个路径值,否则你依然需要重新配置一遍系统变量)

更新:对于版本 go1.18+,可以直接使用 go init 代替 go build,这样做的好处是可以直接省去后面繁琐的变量配置了


此时在命令行输入 swag -v 后可以看见版本号则表示环境变量配置完毕


初始化

进入项目根目录,保证当前目录下存在至少一个 go 文件(比如主入口文件 main.go

当前目录下打开命令行,输入 swag init 即可根据 go 文件自动构建 swagger 文档了;
新生成的文档存放在 docs 文件夹下


快速上手

gin-swagger

官方参考文档https://github.com/swaggo/gin-swagger

项目根目录执行代码安装依赖:

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

简单测试

在测试前务必先执行 swag init 生成对应 docs 文件!

import 内需要手动导入 docs,其余的两个包 goland 会自动处理

通过注释编写接口信息,然后于 main 方法注册 swagger-ui 的界面路由就完毕了

package main

import (
    // 这里需要我们手动导入docs,不然报错
    // 因为该包我们没有在代码中实际引用到,故别名需要取名为下划线
	_ "ginoj/docs"

	"github.com/gin-gonic/gin"

    // 这两个是固定的,不用修改直接复制黏贴导包
	swaggerfiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"

	"net/http"
)

// @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")
}

func main() {
	router := gin.Default()

    // 注册swagger-ui界面路由
	router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))

	router.Run(":10001")
}

此时进入 localhost:8080/swagger/index.html 就可以看见接口文档了(注意这里的端口修改为你使用的那一个!)


详细配置

通过上述操作我们发现依然会提示缺失了 spec 文件,这是我们没有执行 init 的缘故;

注意,每次修改一次文档都必须执行 swag init 一次,并且重启服务器才可以正常渲染;

我们把 main.go 改造为这个样子,为 main 添加了一些全局注释

package main

import (
	_ "ginoj/docs"
	"github.com/gin-gonic/gin"
	swaggerfiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
	"net/http"
)

// Helloworld
// @Description a simple example
// @Tags example
// @Accept json
// @Produce json
// @Param id path int true "shit"
// @Success 200 {string} json "{"status":"success"}"
// @Router /helloworld [get]
func Helloworld(g *gin.Context) {
	g.JSON(http.StatusOK, "helloworld")
}

// @title           Swagger Example API
// @version         1.0
// @description     This is a sample server celler server.
// @termsOfService  http://swagger.io/terms/
// @contact.name   API Support
// @contact.url    http://www.swagger.io/support
// @contact.email  support@swagger.io
// @license.name  MIT
// @license.url   http://www.apache.org/licenses/LICENSE-2.0.html
// @host      localhost:10001
func main() {
	router := gin.Default()
	router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
	router.Run(":10001")
}

回到根目录下执行 swag init,之后重启服务器即可看到文档了


有关Swaggo快速上手的更多相关文章

  1. ruby - 如何以表格格式快速打印 Ruby 哈希值? - 2

    有没有办法快速将表格格式的ruby​​哈希打印到文件中?如:keyAkeyBkeyC...1232343451253474456...其中散列的值是不同大小的数组。还是使用双循环是唯一的方法?谢谢 最佳答案 试试我写的这个gem(在表中打印散列、ruby对象、ActiveRecord对象):http://github.com/arches/table_print 关于ruby-如何以表格格式快速打印Ruby哈希值?,我们在StackOverflow上找到一个类似的问题:

  2. 电脑启动后显示器黑屏怎么办?排查下面4个问题,快速解决 - 2

    电脑启动出现显示器黑屏是一个相当常见的问题。如果您遇到了这个问题,不要惊慌,因为它有很多可能的原因,可以采取一些简单的措施来解决它。在本文中,小编将介绍下面4种常见的电脑启动后显示器黑屏的原因,排查这些原因,快速解决! 演示机型:联想Ideapad700-15ISK-ISE系统版本:Windows10一、显示器问题如果出现电脑启动后显示器黑屏的情况。那么首先您需要检查一下显示器是否正常工作。您可以通过更换另一个显示器或将当前显示器连接到另一台计算机来检查显示器是否存在问题。如果问题仍然存在,那么您可以排除显示器故障的可能性。 二、显卡问题如果您的电脑配备了独立显卡,那么显卡故障也可能是导致电脑

  3. ruby - 使单元测试快速失败以进行突变测试 - 2

    mutationtesting遇到一个问题是它很慢,因为默认情况下您会为每个生成的突变执行完整的测试运行(测试文件或一组测试文件)。加快突变测试的一种方法是,一旦遇到单一故障(但仅在突变测试期间),就停止对给定突变体的测试运行。更好的做法是让变异测试者记住杀死最后一个变异体的第一个测试是什么,并将其首先交给下一个变异体。ruby中是否有任何东西可以做这些事情,或者我最好的选择是开始猴子修补?(是的,我知道单元测试应该很快。显示所有失败的测试在突变测试之外很有用,因为它不仅可以帮助您识别出问题,还可以查明哪里出了问题)编辑:我目前正在对测试/单元使用heckle。如果测试/单元不可能记住

  4. ruby - 使用和不使用 Rails 的快速 (Rspec) 测试 - 2

    我有两个类:1.Sale是ActiveRecord的子类;它的工作是将销售数据持久保存到数据库中。classSale2.SalesReport是一个标准的Ruby类;它的工作是生成和绘制有关销售的信息。classSalesReportdefinitialize(start_date,end_date)@start_date=start_date@end_date=end_dateenddefsales_in_durationSale.total_for_duration(@start_date,@end_date)end#...end因为我想使用TDD并且我希望我的测试运行得非常快,所

  5. ruby - 快速FTP服务器 - 2

    我正在寻找一个快速、无需配置的FTP服务器。完全像Serve的东西或Rack_dav,但对于FTP,它可以通过运行命令来发布文件夹。是否有gem或其他东西可以做这样的事情?解决方案基于Wayne的ftpdgem,我创建了一个快速且易于使用的gem,名为Purvey. 最佳答案 ftpdgem支持TLS,并带有文件系统驱动程序。与em-ftpd一样,您提供一个驱动程序,但该驱动程序不需要做太多事情。这是一个最低限度的FTP服务器,它接受任何用户名/密码,并提供临时目录中的文件:require'ftpd'require'tmpdir'c

  6. ruby - 快速解决字谜 - 2

    给定两个字符串,我想确定它们是否是彼此的变位词。这是我想出的解决方案:#outputmessagesdefanagramputs"Anagram!"exitenddefnot_anagramputs"Notananagram!"exitend#mainmethodif__FILE__==$0#readtwostringsfromthecommandlinefirst,second=gets.chomp,gets.chomp#specialcase1not_anagramiffirst.length!=second.length#specialcase2anagramiffirst==s

  7. 线性代数让我想想:快速求三阶矩阵的逆矩阵 - 2

    快速求三阶矩阵的逆矩阵前言一般情况下,我们求解伴随矩阵是要注意符号问题和位置问题的(如下所示)A−1=1[  ][−[  ]−[  ]−[  ]  −[  ]]=A−1=1[  ][   M11−[M12]   M13−[M21]   M22−[M23]     M31−[M32]   M33]⊤\begin{aligned}&A^{-1}=\frac{1}{[\\]}\left[\begin{array}{cccccc}&-[\\]&\\-[\\]&&-[\\]\\\\&-[\\]&\\\end{array}\right]=\\\\&A^{-1}=\frac{1}{[\\]}\left[\b

  8. 火爆的ChatGPT快速学成,要看哪些书? - 2

    以前我们经常打趣说:***,你out了!当然了,玩笑成分居多。但是如果作为一名技术人员,现在还没有听说过ChatGPT,那么你可能真的“out”了。比尔·盖茨说,ChatGPT的重要性堪比互联网的发明,甚至它“将改变我们的世界”。ChatGPT得到科技界大佬的如此推崇,那么,ChatGPT到底是什么?ChatGPT是2022年11月底,美国OpenAI公司推出的一款人工智能聊天机器人。两个月后,ChatGPT的月活用户已经突破1亿,成为有史以来增长速度最快的消费者应用程序。ChatGPT功能极其强大,它能够通过学习和理解人类的语言进行对话,还能根据上下文进行互动,实现像人类一样的聊天交流。除了

  9. ruby - Ruby 语言中的快速排序 - 2

    我正在尝试在ruby​​中实现快速排序,但卡在如何在pivot的第一个分区之后递归调用。请帮助我了解如何进行,并让我知道到目前为止我的编码风格是否良好。classQuickSort$array=Array.new()$count=0defadd(val)#addingvaluestosorti=0whileval!='000'.to_i$array[i]=val.to_ii=i+1val=gets.to_iendenddeffirstsort_aka_divide(val1,val2,val3)#firstpartition$count=$count+1@pivot=val1@left

  10. ruby - 缓慢的 Ruby 正则表达式通过奇怪的变化变得快速 - 2

    我一直在调试网站以查找页面加载时间过长的根源,并将其缩小为用于从文本中提取URL的正则表达式:/(?:([\w+.-]+):\/\/|(?:www\.))[^\s在一大块文本上运行大约需要3秒。我发现如果我将第一个子句的逆语句添加到正则表达式((?:[^\w+.-]|^))的开头,它几乎会立即运行:/(?:[^\w+.-]|^)(?:([\w+.-]++):\/\/|(?:www\.))[^\s在我看来,添加的子句根本不应该影响正则表达式,因为没有什么可以导致该子句失败(因为这些字符将与“[\w+.-]++”子句匹配)。为什么这会使正则表达式运行得更快?编辑有些人要求提供我正在尝试做的

随机推荐