班级空间网站建设作用,个人网站一键生成,丹徒网站建设机构,餐饮管理系统哪个好golang 引入swagger#xff08;iris、gin#xff09; 在开发过程中#xff0c;我们不免需要调试我们的接口#xff0c;但是有些接口测试工具无法根据我们的接口变化而动态变化。文档和代码是分离的。总是出现文档和代码不同步的情况。这个时候就可以在我们项目中引入swagge…golang 引入swaggeriris、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/swagv1.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/jsongithub.com/kataras/iris/v12github.com/kataras/iris/v12/mvcmyTest/demo_home/swagger_demo/iris/modelnet/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/jsonuser1 : new(model.User)user1.Name zhangsanuser1.Age 20user2 : new(model.User)user2.Name li4user2.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/v12github.com/iris-contrib/swagger/v12/swaggerFilesgithub.com/kataras/iris/v12myTest/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/v12github.com/iris-contrib/swagger/v12/swaggerFilesgithub.com/kataras/iris/v12myTest/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/v12github.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/jsongithub.com/kataras/iris/v12github.com/kataras/iris/v12/mvcmyTest/demo_home/swagger_demo/iris/modelnet/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/jsonuser1 : new(model.User)user1.Name zhangsanuser1.Age 20user2 : new(model.User)user2.Name li4user2.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/responsenet/httpstrconvtimegithub.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:usernamePassword 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{dataLoginResp} 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/ginginSwagger github.com/swaggo/gin-swaggergithub.com/swaggo/gin-swagger/swaggerFilesmyTest/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.ligmail.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 successMsgFail fail
)type Result struct {Code int json:codeData interface{} json:dataMsg 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/ginginSwagger github.com/swaggo/gin-swaggergithub.com/swaggo/gin-swagger/swaggerFilesmyTest/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/responsenet/httpstrconvtimegithub.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:usernamePassword 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{dataLoginResp} 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 successMsgFail fail
)type Result struct {Code int json:codeData interface{} json:dataMsg 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 APIversion必填 提供应用程序API的版本。// version 1.0description应用程序的简短描述。// description This is a sample server celler server.tag.name标签的名称。// tag.name This is the name of the tagtag.description标签的描述。// tag.description Cool Descriptiontag.docs.url标签的外部文档的URL。// tag.docs.url https://example.comtag.docs.description标签的外部文档说明。// tag.docs.description Best example documentationtermsOfServiceAPI的服务条款。// termsOfService http://swagger.io/terms/contact.name公开的API的联系信息。// contact.name API Supportcontact.url联系信息的URL。 必须采用网址格式。// contact.urlcontact.email联系人/组织的电子邮件地址。 必须采用电子邮件地址的格式。// contact.email supportswagger.iolicense.name必填 用于API的许可证名称。// license.name Apache 2.0license.url用于API的许可证的URL。 必须采用网址格式。// license.url http://www.apache.org/licenses/LICENSE-2.0.htmlhost运行API的主机主机名或IP地址。// host localhost:8080BasePath运行API的基本路径。// BasePath /api/v1acceptAPI 可以使用的 MIME 类型列表。 请注意Accept 仅影响具有请求正文的操作例如 POST、PUT 和 PATCH。 值必须如“Mime类型”中所述。// accept jsonproduceAPI可以生成的MIME类型的列表。值必须如“Mime类型”中所述。// produce jsonquery.collection.format请求URI query里数组参数的默认格式csvmultipipestsvssv。 如果未设置则默认为csv。// query.collection.format multischemes用空格分隔的请求的传输协议。// schemes http httpsx-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/v2engine.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,commentfailure以空格分隔的故障响应。return code,{param type},data type,commentresponse与success、failure作用相同header以空格分隔的头字段。 return code,{param type},data type,commentrouter以空格分隔的路径定义。 path,[httpMethod]x-name扩展字段必须以x-开头并且只能使用json值。 // Summary 测试swagger
// Tags test
// version 1.0
// Success 200 object FinalResult{datav1.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的类型支持 querypathheaderbodyformData
如果我们需要给字段添加注释直接在字段后面添加即可 直接在参数属性后面增加注释也可以指定参数的名称说明描述 type Application struct {Id int json:id example:2 // 环境IDName string json:name example:环境一 // Name 环境名称
}忽略某个字段
type Account struct {ID string json:idName string json:nameIgnored 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生成文档
