gin-swagger 生成RESTful风格OpenAPI文档

:scroll:什么是swagger

Swagger 是一个 API 生成工具,可以生成文档。 Swagger 是通过编写 yamljson 来实现文档化。并且可以进行测试等工作。

通过 swagger 可以方便的生成接口文档,方便前端进行查看和测试。

:wrench:安装 swagger

在我们的项目中集成 swagger ,以后项目的接口文档便可以自动生成

安装之前建议开启go mod,使用goproxy下载

首先得安装swagger

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

验证是否安装成功

$ swag -v
swag version v1.6.7复制代码

:hamburger:集成 swagger

安装 gin-swagger

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

$ go get -u github.com/swaggo/gin-swagger/swaggerFiles复制代码

gin路由配置

router

中添加路由,这个路由是对 swagger 的访问地址来进行添加的

url := ginSwagger.URL("http://localhost:8080/swagger/doc.json") router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))

其中 url 定义了 swaggerdoc.json 路径,我们可以直接访问该 json 来进行查看。

文档配置

接下来就是完善文档:

main.gomain 方法上添加注释

package main

import (
	_ "GinHello/docs" //此处导入的是swag init 生成docs文件所在路径
	"GinHello/initRouter" //导入路由
)

// @title Gin swagger
// @version 1.0
// @description Gin swagger 示例项目

// @contact.name ganlei
// @contact.url https://juejin.im/user/5e9f9b15f265da47b55504de
// @contact.email ganlei@uniontech.com

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host localhost:9090
func main() {
    // 省略其他代码
}
复制代码

上述的注释基本都是很好理解的,不做过多解释。

主要的项目介绍注释就是这些,接下来进行我们的接口方法注释。

在我们的 handler 中添加注释

Swagger 中需要将相应的注释或注解编写到方法上,再利用生成器自动生成说明文件

gin-swagger 给出的范例:

// @Summary Add a new pet to the store
// @Description get string by ID
// @Accept  json
// @Produce  json
// @Param   some_id     path    int     true        "Some ID"
// @Success 200 {string} string    "ok"
// @Failure 400 {object} web.APIError "We need ID!!"
// @Failure 404 {object} web.APIError "Can not find ID"
// @Router /testapi/get-string-by-int/{some_id} [get]复制代码

我们可以参照 Swagger 的注解规范和范例去编写

参考的注解请参见 官方文档 。 以确保获取最新的 swag 语法

其中文档中没有说明的地方这里说明一下,关于 Param参数类型有以下几种

/user?username=Jack&age=18
/user/1

不同的参数类型对应的不同请求,请对应使用。

我们对路径传参形如
/user/:name 的接口,最后的 name 通过
{} 包裹。

通常 @Success、 @Failure 返回结果可以包装成一个结构体model.Result

package model

type Result struct {
        Result bool         `json:"result" example:"请求结果true或者false"`
	Code    int         `json:"code" example:"000"`
	Data    interface{} `json:"data" `
}
复制代码

我们在对
Result 中的
tag 会有
example ,这个仍旧是
swagger 的标签,用来给该结构体一个示例。

生成swagger对应的文件

当我们完成了所有的代码注释时,在控制台中重新执行 swag init ,它会根据我们的注释生成 docs.go 及其对应的 json 和 yaml 文件。

需注意 swag init 指令需在项目 目录 下执行,这样swag可以扫描整个项目中的swagger注释

通过指令:

swag init -h 

可以查看相关帮助,如果main.go函数不在项目根目录的话,可以使用以下指令:

swag init -g ./../main.go - o ./docs复制代码

这里用的是相对路径,相对你的项目根目录main.go所在位置

补充说明

main.go文件中的main上方注释,有一个@BasePath,通常在使用域名解析时,以这种形式/api/v1访问api接口

如果有遇到跨域问题,可以在 Router 中加上处理函数

//Cors ...允许跨域设置func Cors() gin.HandlerFunc {    return func(c *gin.Context) {        c.Header("Access-Control-Allow-Origin", "*")        c.Header("Access-Control-Allow-Credentials", "false")        c.Next()    }}复制代码

验证

启动我们的项目,访问 hppt://localhost:9090/swagger/index.html 就可以查看我们的文档,效果如下

gin-swagger 生成RESTful风格OpenAPI文档

gin-swagger 生成RESTful风格OpenAPI文档

总结

通过本章节的学习,将我们的项目和文档相结合起来,反正要写注释,现在是一举两得,即完成了代码注释,也完成了项目文档。

原文 

https://juejin.im/post/5eec1d76f265da02c46e9863

本站部分文章源于互联网,本着传播知识、有益学习和研究的目的进行的转载,为网友免费提供。如有著作权人或出版方提出异议,本站将立即删除。如果您对文章转载有任何疑问请告之我们,以便我们及时纠正。

PS:推荐一个微信公众号: askHarries 或者qq群:474807195,里面会分享一些资深架构师录制的视频录像:有Spring,MyBatis,Netty源码分析,高并发、高性能、分布式、微服务架构的原理,JVM性能优化这些成为架构师必备的知识体系。还能领取免费的学习资源,目前受益良多

转载请注明原文出处:Harries Blog™ » gin-swagger 生成RESTful风格OpenAPI文档

赞 (0)
分享到:更多 ()

评论 0

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址