文章详情

短信预约-IT技能 免费直播动态提醒

请输入下面的图形验证码

提交验证

短信预约提醒成功

Swaggo零基础入门教程

2023-01-28 09:00

关注

配置流程

注意区分

go-swagger != swaggo

二者功能差不多,都是生成接口文档用的;

前者构建速度极慢且官方文档极不友好;

后者构建速度快且上手简单,故我们这里采用它;

下载swaggo

项目根目录下(即与 go.mod 同级的文件夹)命令行执行此代码,下载 swaggo

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

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

更新:对于版本 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零基础入门教程的文章就介绍到这了,更多相关Swaggo入门内容请搜索编程网以前的文章或继续浏览下面的相关文章希望大家以后多多支持编程网!

阅读原文内容投诉

免责声明:

① 本站未注明“稿件来源”的信息均来自网络整理。其文字、图片和音视频稿件的所属权归原作者所有。本站收集整理出于非商业性的教育和科研之目的,并不意味着本站赞同其观点或证实其内容的真实性。仅作为临时的测试数据,供内部测试之用。本站并未授权任何人以任何方式主动获取本站任何信息。

② 本站未注明“稿件来源”的临时测试数据将在测试完成后最终做删除处理。有问题或投稿请发送至: 邮箱/279061341@qq.com QQ/279061341

软考中级精品资料免费领

  • 历年真题答案解析
  • 备考技巧名师总结
  • 高频考点精准押题
  • 2024年上半年信息系统项目管理师第二批次真题及答案解析(完整版)

    难度     813人已做
    查看
  • 【考后总结】2024年5月26日信息系统项目管理师第2批次考情分析

    难度     354人已做
    查看
  • 【考后总结】2024年5月25日信息系统项目管理师第1批次考情分析

    难度     318人已做
    查看
  • 2024年上半年软考高项第一、二批次真题考点汇总(完整版)

    难度     435人已做
    查看
  • 2024年上半年系统架构设计师考试综合知识真题

    难度     224人已做
    查看

相关文章

发现更多好内容

猜你喜欢

AI推送时光机
位置:首页-资讯-后端开发
咦!没有更多了?去看看其它编程学习网 内容吧
首页课程
资料下载
问答资讯