七叶笔记 » golang编程 » Gin 生成 Swagger 文档

Gin 生成 Swagger 文档

分类: golang编程 | 浏览: 282

Gin 生成 Swagger 文档

环境介绍

  • 开发环境：windows10 x64
  • Golang：1.16
  • Gin:1.7.0

安装 Swagger

idel 配置 go mod 由于我已经默认你已经安装 gin 框架 ，所以我直接在项目根目录下安装 swag 依赖 

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

调用方法注释

Swagger 生成文档原理就是 扫描程序文件中，方法注释 。所以在方法上添加规范注释，由为关键 Swagger 标准注释[2] 

 // AdminLogin godoc
// @Summary 管理员登陆
// @Description 管理员登陆
// @Tags 管理员接口
// @ID /admin_login/login
// @Accept  json
// @Produce  json
// @Param body body dto.AdminLoginInput true "body"    # [值得名称] body [值得类型] [是否必传] "[返回值名称]"
// @Success 200 {object} middleware.Response{data=dto.DemoInput} "success"
// @Router /admin_login/login [post]
func (adminlogin *AdminLoginController) AdminLogin(ctx *gin.Context) {
    // 定义传入数据结构
    params:=&dto.AdminLoginInput{}
    if err:=params.BindValidParam(ctx); err != nil {
        middleware.ResponseError(ctx, 1001, err)
        return
    }


    out:=&dto.AdminLoginOutput{Token:params.UserName}
    middleware.ResponseSuccess(ctx,out)
}

swagger 设入 Gin router

文件 router/route.go 

 # 加载依赖
import (
    "[项目名称]/docs"
    "github.com/gin-gonic/gin"
    "github.com/swaggo/files"
    "github.com/swaggo/gin-swagger"
)


func InitHttpServer() {
    var router *gin.Engine
    router = gin.Default()
    router.Static("/html", "./public")


    // 设置 swagger 访问路由
    router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))


    router.Run(":" + _const.HTTP_SERVER_PORT)
}

Swagger 生成 API 文档

项目根目录下 命令行 执行命令 swag init

swag init 命令会在项目根目录下生成文件夹 docs 。

访问 swagger 生成文档

项目根目录执行命令 go run main.go 启动网络服务。具体看你的gin 设置服务端口，使用浏览器访问 设置端口]/swagger/index.html 就可以看到刚才生成的接口文档

References

[1] 更多往期文章在我的个人博客:
[2] Swagger 标准注释:

相关文章