[go-swagger]在go语言中使用swagger教程-CSDN博客

本文链接：https://blog.csdn.net/m0_59314648/article/details/148154254

1、引言

1.1、什么是swagger

Swagger 是一个强大的测试工具，用于设计、构建、记录和使用 RESTful Web 服务。它提供了一种标准化的方式来描述和文档化 API，使得开发人员可以更轻松地理解和使用这些 API。

1.2、为什么要用swagger

swagger可以根据API的定义自动生成交互性的文档，这些文档是动态生成的，能够实时反应api的现状。节省时间，开发人员无需手动编写和维护 API 文档。减少错误，自动生成的文档减少了因手动编写而导致的错误。快速测试，开发人员和测试人员可以快速测试 API 的功能，而无需编写额外的测试代码。

2、在go语言中安装swagger

1、安装swagger

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

2、检验安装是否成功

swag -v
swag version v1.7.0

3、安装go-swagger的扩展

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

4、使用 swag CLI 生成文档，运行下列命令生成swagger文档（默认生成 docs.go、swagger.json 和 swagger.yaml 文件）。

swag init

3、编写带有swagger注释的代码

1、在main.go中导包

import(
   swaggerFiles "github.com/swaggo/files"
   ginSwagger "github.com/swaggo/gin-swagger"
   _ "yoloblog1.0/docs"       //之前使用swag init 生成的swagger文档的路径
)

2、在具体的路由处理函数上方添加注释，定义该接口的行为。

// Register
// @Summary 用户注册
// @Produce json
// @Param user body system.SysUser true "用户信息"
// @Success 200 {object} system.SysUser
// @Failure 400 {string} string "注册失败"
// @Router /user/register [post]
func (m *UserApi) Register(c *gin.Context) {
   var user system.SysUser
   c.ShouldBindJSON(&user)
   err := userService.Register(&user)
   if err != nil {
       c.JSON(http.StatusOK, gin.H{
           "status": global.FAIL,
           "msg": err.Error(),
       })
       return
   }
   c.JSON(http.StatusOK, gin.H{
       "status": global.SUCCESS,
       "msg": "success",
   })
   return
}

@Summary：接口简述
@Produce：返回的 MIME 类型
@Param：参数定义（格式：名称位置类型是否必填描述）
@Success：成功响应（格式：状态码 {类型} 数据结构描述）
@Failure：失败响应
@Router：路由路径和方法

3、在gin路由中声明swagger的接口

func main() {
   global.Router = gin.Default()
   global.Router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
   global.Router.Run(":8080")
}

4、重新初始化swagger