golang 引入swagger（iris、gin）

golang 引入swagger（iris、gin）

在开发过程中，我们不免需要调试我们的接口，但是有些接口测试工具无法根据我们的接口变化而动态变化。文档和代码是分离的。总是出现文档和代码不同步的情况。这个时候就可以在我们项目中引入swagger，方便后期维护以及他人快速上手项目

0 下载swagger

# 1 安装swagger
# 在go.mod目录所在位置执行命令
go get -u github.com/swaggo/swag/cmd/swag# 查看是否安装成功
swag -v# 如果发现报错：zsh: command not found: swag，则需要手动编译生成swag
cd $GOPATH/pkg/mod/github.com/swaggo/swag@v1.16.2/cmd/swag/
sudo go build
sudo mv swag $GOPATH/bin
# 查看是否安装成功
swag -v

在这里插入图片描述

1 iris引入swagger

①导入iris-contrib/swagger依赖

//安装swagger扩展,本项目使用的是iris最新版（iris/v12），因此需要安装iris-swagger/v12扩展go get -v "github.com/iris-contrib/swagger/swaggerFiles"
go get -v "github.com/iris-contrib/swagger/v12"

②添加对应swagger注解 & swag init生成docs

在项目对应文件添加swagger注解，并通过swag init生成docs
注意：如果代码中的swagger注释有修改，需要重新执行swag init生成文档

例如：我给controller添加注解：

package controllerimport ("encoding/json""github.com/kataras/iris/v12""github.com/kataras/iris/v12/mvc""myTest/demo_home/swagger_demo/iris/model""net/http"
)type UserController struct {Ctx iris.Context
}func (u *UserController) BeforeActivation(b mvc.BeforeActivation) {b.Handle(http.MethodGet, "/getAll", "GetAllUsers")
}// GetAllUsers @Summary 获取用户信息
// @Description 获取所有用户信息
// @Tags 用户
// @Accept json
// @Produce json
// @Router /user/getAll [get]
func (u *UserController) GetAllUsers() mvc.Result {//手动模拟从数据库查询到user信息resp := new(mvc.Response)resp.ContentType = "application/json"user1 := new(model.User)user1.Name = "zhangsan"user1.Age = 20user2 := new(model.User)user2.Name = "li4"user2.Age = 28users := []model.User{*user1, *user2}marshal, _ := json.Marshal(users)resp.Content = marshalresp.Code = http.StatusOKreturn resp
}

//在项目根目录执行swag init ( 默认会找当前目录下的 main.go 文件，如果不叫 main.go 也可以-g手动指定文件位置。)
swag init # swag init -g cmd/api/api.go -o cmd/api/docs (-o指定docs生成位置)

③main.go中引入swag生成doc包

在 main.go 中导入刚才生成的 docs 包

package mainimport ("github.com/iris-contrib/swagger/v12""github.com/iris-contrib/swagger/v12/swaggerFiles""github.com/kataras/iris/v12""myTest/demo_home/swagger_demo/iris/controller"_ "myTest/demo_home/swagger_demo/iris/docs" //引入docs包
)func main() {app := iris.New()controller.InitControllers(app)config := &swagger.Config{URL: "http://localhost:8080/swagger/doc.json", //The url pointing to API definition}app.Get("/swagger/{any}", swagger.CustomWrapHandler(config, swaggerFiles.Handler))app.Listen(":8080")
}

④运行程序访问ip:port/swagger/index.html页面

运行main.go，浏览器输入：http://localhost:8080/swagger/index.html

在这里插入图片描述

全部代码

Github：
https://github.com/ziyifast/ziyifast-code_instruction/tree/main/swagger_demo

项目结构：
在这里插入图片描述

main.go
package mainimport ("github.com/iris-contrib/swagger/v12""github.com/iris-contrib/swagger/v12/swaggerFiles""github.com/kataras/iris/v12""myTest/demo_home/swagger_demo/iris/controller"_ "myTest/demo_home/swagger_demo/iris/docs" # 引入生成的docs包
)func main() {app := iris.New()controller.InitControllers(app)config := &swagger.Config{URL: "http://localhost:8080/swagger/doc.json", //The url pointing to API definition}app.Get("/swagger/{any}", swagger.CustomWrapHandler(config, swaggerFiles.Handler))app.Listen(":8080")
}
controller/controllers.go
package controllerimport ("github.com/kataras/iris/v12""github.com/kataras/iris/v12/mvc"
)func InitControllers(app *iris.Application) {myMvc := mvc.New(app.Party("/user"))myMvc.Handle(new(UserController))
}
controller/user_controller.go
package controllerimport ("encoding/json""github.com/kataras/iris/v12""github.com/kataras/iris/v12/mvc""myTest/demo_home/swagger_demo/iris/model""net/http"
)type UserController struct {Ctx iris.Context
}func (u *UserController) BeforeActivation(b mvc.BeforeActivation) {b.Handle(http.MethodGet, "/getAll", "GetAllUsers")
}// GetAllUsers @Summary 获取用户信息
// @Description 获取所有用户信息
// @Tags 用户
// @Accept json
// @Produce json
// @Router /user/getAll [get]
func (u *UserController) GetAllUsers() mvc.Result {//手动模拟从数据库查询到user信息resp := new(mvc.Response)resp.ContentType = "application/json"user1 := new(model.User)user1.Name = "zhangsan"user1.Age = 20user2 := new(model.User)user2.Name = "li4"user2.Age = 28users := []model.User{*user1, *user2}marshal, _ := json.Marshal(users)resp.Content = marshalresp.Code = http.StatusOKreturn resp
}

2 gin引入swagger

①导入swaggo/gin-swagger依赖

// 引入gin及gin-swagger依赖
go get "github.com/gin-gonic/gin"
go get "github.com/swaggo/gin-swagger/swaggerFiles"
go get "github.com/swaggo/gin-swagger"

②添加对应swagger注解 & swag init生成docs

注意：如果代码中的swagger注释有修改，需要重新执行swag init生成文档
user_controller.go

package controllerimport (ret "myTest/demo_home/swagger_demo/gin/response""net/http""strconv""time""github.com/gin-gonic/gin"
)// Hello 测试
// @Summary      测试SayHello
// @Description  向你说Hello
// @Tags         测试
// @Accept       json
// @Produce      json
// @Param        who  query     string  true             "人名"
// @Success      200  {string}  string  "{"msg": "hello  lixd"}"
// @Failure      400  {string}  string  "{"msg": "who    are  you"}"
// @Router       /hello [get]
func Hello(c *gin.Context) {who := c.Query("who")if who == "" {c.JSON(http.StatusBadRequest, gin.H{"msg": "who are u?"})return}c.JSON(http.StatusOK, gin.H{"msg": "hello " + who})
}type LoginReq struct {Username string `json:"username"`Password string `json:"password"`
}
type LoginResp struct {Token string `json:"token"`
}// Login 登陆
// @Summary      登陆
// @Tags         登陆注册
// @Description  登入
// @Accept       json
// @Produce      json
// @Param        user  body      LoginReq                    true  "用户名密码"
// @Success      200   {object}  ret.Result{data=LoginResp}  "token"
// @Failure      400   {object}  ret.Result                  "错误提示"
// @Router       /login [post]
func Login(c *gin.Context) {var m LoginReqif err := c.ShouldBind(&m); err != nil {c.JSON(http.StatusBadRequest, ret.Fail("参数错误"))return}if m.Username == "admin" && m.Password == "123456" {resp := LoginResp{Token: strconv.Itoa(int(time.Now().Unix()))}c.JSON(http.StatusOK, ret.Success(resp))return}c.JSON(http.StatusUnauthorized, ret.Fail("user  or  password  error"))
}

③main.go中引入swag生成doc包

package mainimport ("github.com/gin-gonic/gin"ginSwagger "github.com/swaggo/gin-swagger""github.com/swaggo/gin-swagger/swaggerFiles""myTest/demo_home/swagger_demo/gin/controller"_ "myTest/demo_home/swagger_demo/gin/docs"
)var swagHandler gin.HandlerFunc// @title           Swagger Example API
// @version         1.0
// @description     This is a sample server.
// @termsOfService  https://lixueduan.com// @contact.name   lixd
// @contact.url    https://lixueduan.com
// @contact.email  xueduan.li@gmail.com// @license.name  Apache 2.0
// @license.url   http://www.apache.org/licenses/LICENSE-2.0.html// @host      localhost:8080
// @BasePath  /api/v1// SwaggerUI: http://localhost:8080/swagger/index.html
func main() {e := gin.Default()v1 := e.Group("/api/v1"){v1.GET("/hello", controller.Hello)v1.POST("/login", controller.Login)}e.GET("swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))if swagHandler != nil {e.GET("/swagger/*any", swagHandler)}if err := e.Run(":8080"); err != nil {panic(err)}
}

resp.go:

// Package ret 统一返回结构
package retimport ("net/http"
)const (MsgSuccess = "success"MsgFail    = "fail"
)type Result struct {Code int         `json:"code"`Data interface{} `json:"data"`Msg  string      `json:"msg"`
}func Success(data interface{}, msg ...string) *Result {var m = MsgSuccessif len(msg) > 0 {m = msg[0]}return &Result{Code: http.StatusOK,Data: data,Msg:  m,}
}func Fail(msg ...string) *Result {var m = MsgFailif len(msg) > 0 {m = msg[0]}return &Result{Code: http.StatusBadRequest,Data: "",Msg:  m,}
}

④运行程序访问ip:port/swagger/index.html

http://localhost:8080/swagger/index.html

在这里插入图片描述

全部代码

地址：
https://github.com/ziyifast/ziyifast-code_instruction/tree/main/swagger_demo

main.go
package mainimport ("github.com/gin-gonic/gin"ginSwagger "github.com/swaggo/gin-swagger""github.com/swaggo/gin-swagger/swaggerFiles""myTest/demo_home/swagger_demo/gin/controller"_ "myTest/demo_home/swagger_demo/gin/docs"
)var swagHandler gin.HandlerFunc// @title           Swagger Example API
// @version         1.0
// @description     This is a sample server.// @contact.name   lixd
// @contact.name   ziyi
// @contact.url    https://github.com/ziyifast/ziyifast-code_instruction/tree/main/swagger_demo// @license.name  Apache 2.0
// @license.url   http://www.apache.org/licenses/LICENSE-2.0.html// @host      localhost:8080
// @BasePath  /api/v1// SwaggerUI: http://localhost:8080/swagger/index.html
func main() {e := gin.Default()v1 := e.Group("/api/v1"){v1.GET("/hello", controller.Hello)v1.POST("/login", controller.Login)}e.GET("swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))if swagHandler != nil {e.GET("/swagger/*any", swagHandler)}if err := e.Run(":8080"); err != nil {panic(err)}
}
controller/user_controller.go
package controllerimport (ret "myTest/demo_home/swagger_demo/gin/response""net/http""strconv""time""github.com/gin-gonic/gin"
)// Hello 测试
// @Summary      测试SayHello
// @Description  向你说Hello
// @Tags         测试
// @Accept       json
// @Produce      json
// @Param        who  query     string  true             "人名"
// @Success      200  {string}  string  "{"msg": "hello  lixd"}"
// @Failure      400  {string}  string  "{"msg": "who    are  you"}"
// @Router       /hello [get]
func Hello(c *gin.Context) {who := c.Query("who")if who == "" {c.JSON(http.StatusBadRequest, gin.H{"msg": "who are u?"})return}c.JSON(http.StatusOK, gin.H{"msg": "hello " + who})
}type LoginReq struct {Username string `json:"username"`Password string `json:"password"`
}
type LoginResp struct {Token string `json:"token"`
}// Login 登陆
// @Summary      登陆
// @Tags         登陆注册
// @Description  登入
// @Accept       json
// @Produce      json
// @Param        user  body      LoginReq                    true  "用户名密码"
// @Success      200   {object}  ret.Result{data=LoginResp}  "token"
// @Failure      400   {object}  ret.Result                  "错误提示"
// @Router       /login [post]
func Login(c *gin.Context) {var m LoginReqif err := c.ShouldBind(&m); err != nil {c.JSON(http.StatusBadRequest, ret.Fail("参数错误"))return}if m.Username == "admin" && m.Password == "123456" {resp := LoginResp{Token: strconv.Itoa(int(time.Now().Unix()))}c.JSON(http.StatusOK, ret.Success(resp))return}c.JSON(http.StatusUnauthorized, ret.Fail("user  or  password  error"))
}
response/response.go
// Package ret 统一返回结构
package retimport ("net/http"
)const (MsgSuccess = "success"MsgFail    = "fail"
)type Result struct {Code int         `json:"code"`Data interface{} `json:"data"`Msg  string      `json:"msg"`
}func Success(data interface{}, msg ...string) *Result {var m = MsgSuccessif len(msg) > 0 {m = msg[0]}return &Result{Code: http.StatusOK,Data: data,Msg:  m,}
}func Fail(msg ...string) *Result {var m = MsgFailif len(msg) > 0 {m = msg[0]}return &Result{Code: http.StatusBadRequest,Data: "",Msg:  m,}
}

3 注解

3.1 swagger主文件注解-通用API信息

注释说明示例
title必填 应用程序的名称// @title Swagger Example API
version必填 提供应用程序API的版本。// @version 1.0
description应用程序的简短描述。// @description This is a sample server celler server.
tag.name标签的名称。// @tag.name This is the name of the tag
tag.description标签的描述。// @tag.description Cool Description
tag.docs.url标签的外部文档的URL。// @tag.docs.url https://example.com
tag.docs.description标签的外部文档说明。// @tag.docs.description Best example documentation
termsOfServiceAPI的服务条款。// @termsOfService http://swagger.io/terms/
contact.name公开的API的联系信息。// @contact.name API Support
contact.url联系信息的URL。 必须采用网址格式。// @contact.url
contact.email联系人/组织的电子邮件地址。 必须采用电子邮件地址的格式。// @contact.email support@swagger.io
license.name必填 用于API的许可证名称。// @license.name Apache 2.0
license.url用于API的许可证的URL。 必须采用网址格式。// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
host运行API的主机（主机名或IP地址）。// @host localhost:8080
BasePath运行API的基本路径。// @BasePath /api/v1
acceptAPI 可以使用的 MIME 类型列表。 请注意，Accept 仅影响具有请求正文的操作，例如 POST、PUT 和 PATCH。 值必须如“Mime类型”中所述。// @accept json
produceAPI可以生成的MIME类型的列表。值必须如“Mime类型”中所述。// @produce json
query.collection.format请求URI query里数组参数的默认格式：csv，multi，pipes，tsv，ssv。 如果未设置，则默认为csv。// @query.collection.format multi
schemes用空格分隔的请求的传输协议。// @schemes http https
x-name扩展的键必须以x-开头，并且只能使用json值// @x-example-key {“key”: “value”}

通用api信息，部分可以是在docs包里生成的，可以在项目启动的时候，或者在注册swagger路由的时候，修改掉部分信息，或者动态注入部分不固定的值，比如项目的基础路径：BasePath

func NewRouter() *gin.Engine {gin.SetMode("debug")engine := gin.New()docs.SwaggerInfo.BasePath = "/api/v2"engine.POST("/", v1.GetWord)engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))engine.GET("/log/:id", client.ReadLokiLog)return engine
}

3.2 单个API样例

注释样例
description操作行为的详细说明。
description.markdown应用程序的简短描述。该描述将从名为endpointname.md的文件中读取。
id用于标识操作的唯一字符串。在所有API操作中必须唯一。
tags每个API操作的标签列表，以逗号分隔。
summary该操作的简短摘要。
acceptAPI 可以使用的 MIME 类型列表。 请注意，Accept 仅影响具有请求正文的操作，例如 POST、PUT 和 PATCH。 值必须如“Mime类型”中所述。
produceAPI可以生成的MIME类型的列表。值必须如“Mime类型”中所述。
param用空格分隔的参数。param name,param type,data type,is mandatory?,comment attribute(optional)
security每个API操作的安全性。
success以空格分隔的成功响应。return code,{param type},data type,comment
failure以空格分隔的故障响应。return code,{param type},data type,comment
response与success、failure作用相同
header以空格分隔的头字段。 return code,{param type},data type,comment
router以空格分隔的路径定义。 path,[httpMethod]
x-name扩展字段必须以x-开头，并且只能使用json值。

// @Summary 测试swagger
// @Tags test
// @version 1.0
// @Success 200 object FinalResult{data=v1.Application} 成功后返回值
// @Failure 500 object FinalResult 添加失败
// @Router / [get]
func GetWord(ctx *gin.Context) {application := &Application{Id: 1}err := ctx.BindJSON(application)if err != nil {ctx.JSON(500, "")}ctx.JSON(200, SuccessResult(application))
}

summary 是这个api的名字，可以显示在yapi的名称
tag 是这个api所在的分组
success 支持组合嵌套
param 说明了api需要的请求参数
param的类型支持：

  • query
  • path
  • header
  • body
  • formData

如果我们需要给字段添加注释，直接在字段后面添加即可

直接在参数属性后面增加注释，也可以指定参数的名称说明描述

type Application struct {Id   int    `json:"id" example:"2"`     // 环境IDName string `json:"name" example:"环境一"` // Name 环境名称
}

忽略某个字段：

type Account struct {ID   string    `json:"id"`Name string     `json:"name"`Ignored int     `swaggerignore:"true"`
}

注意：如果代码中的swagger注释有修改，需要重新执行swag init生成文档

参考：https://blog.csdn.net/qq_38371367/article/details/123005909

bug

1 unknown field LeftDelim in struct literal of type "github.com/swaggo/swag

注意：如果遇到报错：
docs/docs.go:30:2: unknown field LeftDelim in struct literal of type “github.com/swaggo/swag”.Spec
可能是由于swag版本过低导致，升级版本即可:go get -u -v github.com/swaggo/swag/cmd/swag

2 添加了swag 注解，访问页面成功，但没有对应的方法

重新执行swag init，然后重新启动项目

  • 如果代码中的swagger注解有修改，需要重新执行swag init生成文档

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.hqwc.cn/news/457020.html

如若内容造成侵权/违法违规/事实不符，请联系编程知识网进行投诉反馈email:809451989@qq.com，一经查实，立即删除！

相关文章

[自然语言处理|NLP] 文本分类与情感分析，数据预处理流程，包括了同义词替换和拼写纠正，以及使用NLTK库和TextBlob库进行标记化和情感分析（附代码）

[自然语言处理|NLP] 文本分类与情感分析，数据预处理流程，包括了同义词替换和拼写纠正，以及使用NLTK库和TextBlob库进行标记化和情感分析（附代码）

[自然语言处理|NLP] 文本分类与情感分析，数据预处理流程，包括了同义词替换和拼写纠正，以及使用NLTK库和TextBlob库进行标记化和情感分析（附代码）。 自然语言处理（Natural Language Processing，简称NLP）是人工智能领域的一个重要分支，涉及了处理和理解人类语言的技术…
阅读更多...
网工内推 | 上市公司运维岗，红帽认证优先，带薪年假，节日福利

网工内推 | 上市公司运维岗，红帽认证优先，带薪年假，节日福利

01 捷科智诚 招聘岗位：配置管理岗-运维 职责描述： 1.负责日常配置管理平台的维护及优化，包括权限管理、基线管理、版本管理、发布管理、变更管理等； 2.负责维护各个管理平台的用户管理、权限管理、项目初始化等工作； …
阅读更多...
睿尔曼超轻量仿人机械臂-- RM65-B手眼标定使用说明

睿尔曼超轻量仿人机械臂-- RM65-B手眼标定使用说明

一、前言 机器人的视觉系统分为固定场景视觉系统和运动的「手-眼」视觉系统。相机与机器人手臂末端，构成手眼视觉系统。根据相机在机器人安装位置的不同，手眼视觉系统分为Eye-in-Hand系统（眼在手上）和Eye-to-Hand系统&#xff08…
阅读更多...
【芯片设计- RTL 数字逻辑设计入门 10 -- 奇偶校验实现】

【芯片设计- RTL 数字逻辑设计入门 10 -- 奇偶校验实现】

文章目录 奇偶校验单目运算符（|,^,&）verilog codeverilog codetestbench code 问题总结 奇偶校验 现在需要对输入的32位数据进行奇偶校验,根据sel输出校验结果。 实际上这里做的是奇偶检测，如果是奇数个 1 则结果为 1，使用…
阅读更多...
代码随想录算法训练营第四十五天（动态规划篇）|01背包

代码随想录算法训练营第四十五天（动态规划篇）|01背包

01背包理论基础 学习资料：代码随想录 (programmercarl.com) 相关链接：题目页面 (kamacoder.com) 背包题目分类 01背包定义 有n件物品和一个最多能背重量为w 的背包。第i件物品的重量是weight[i]，得到的价值是value[i] 。每件物品只能用一次…
阅读更多...
uniCloud ---- schema2code

uniCloud ---- schema2code

目录 schema2code有两种方式 label属性 component属性 group属性 应用 DB Schema里有大量的信息，其实有了这些信息，前端将无需自己开发表单维护界面，uniCloud可以自动生成新增、修改、列表、详情的前端页面，以及admin端的列…
阅读更多...
在openSUSE-Leap-15.5-DVD-x86_64中使用deepin-wine-8.16再使用微信3.9.7.29

在openSUSE-Leap-15.5-DVD-x86_64中使用deepin-wine-8.16再使用微信3.9.7.29

在openSUSE-Leap-15.5-DVD-x86_64中使用deepin-wine-8.16再使用微信3.9.7.29 《在openSUSE-Leap-15.5-DVD-x86_64中使用deepin-wine-6.0.0.62再使用微信3.9.5》 https://blog.csdn.net/weixin_42145772/article/details/135074804?spm1001.2014.3001.5501 按照上面文章的方法…
阅读更多...
【iOS ARKit】人形提取

【iOS ARKit】人形提取

为解决人形分离和深度估计问题，ARKit 新增加了 Segmentation Buffer（人体分隔缓冲区）和Estimated Depth Data Buffer（深度估计缓冲区）两个缓冲区。人体分隔缓冲区作用类似于图形渲染管线中的 Stencil Buffer&#xff0…
阅读更多...
挂耳耳机哪个牌子好？推荐几款性价比超高的挂耳耳机

挂耳耳机哪个牌子好？推荐几款性价比超高的挂耳耳机

在寻求更轻便舒适的听音体验时，挂耳耳机逐渐成为众多用户的优先选择。市场上各式各样的耳挂耳机琳琅满目，种类繁多，挂耳耳机哪个牌子好？为了帮助大家更好地了解耳挂耳机的市场状况，我推荐几款性价比超高的挂耳耳机。 挂…
阅读更多...
《Python 网络爬虫简易速速上手小册》第7章：如何绕过反爬虫技术？（2024 最新版）

《Python 网络爬虫简易速速上手小册》第7章：如何绕过反爬虫技术？（2024 最新版）

文章目录 7.1 识别和应对 CAPTCHA7.1.1 重点基础知识讲解7.1.2 重点案例：使用Tesseract OCR识别简单CAPTCHA7.1.3 拓展案例 1：使用深度学习模型识别复杂CAPTCHA7.1.4 拓展案例 2：集成第三方 CAPTCHA 解决服务 7.2 IP 轮换与代理的使用7.2.1 重…
阅读更多...
react 之 UseMemo

react 之 UseMemo

useMemo 看个场景 下面我们的本来的用意是想基于count的变化计算斐波那契数列之和，但是当我们修改num状态的时候，斐波那契求和函数也会被执行，显然是一种浪费 // useMemo // 作用：在组件渲染时缓存计算的结果import { useState …
阅读更多...
Flex 布局教程

Flex 布局教程

目录 一、Flex 布局是什么？ 二、基本概念 三、容器的属性 1、flex-direction属性 2、flex-wrap属性 3、flex-flow属性 4、justify-content属性 5、align-items属性 6、align-content属性 四、项目的属性 1、order属性 2、 flex-grow属性 3、flex-s…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023