gin swagger使用

==背景==

一直都是使用showdoc来管理接口文档，有些麻烦。

在网上调查了一下自动管理文档的插件，发现大家都在用swagger，

于是尝试用一下gin-swagger插件

 

==版本==

go版本：1.18

 

==插件安装==

1、安装swag命令插件，用于执行swag命令

go get github.com/swaggo/swag/cmd/swag
go install github.com/swaggo/swag/cmd/swag

 

2、安装swagger插件

go get github.com/swaggo/gin-swagger
go get github.com/swaggo/files

 

==接口代码==

package main

import (
    "fmt"
    "github.com/gin-gonic/gin"
    swaggerFiles "github.com/swaggo/files"
    ginSwagger "github.com/swaggo/gin-swagger"
    _ "golang-demo/docs"
)

// @title goweb project
// @version 1.0
// @description this is goweb server.
// @host 127.0.0.1:6912
// @BasePath /api/v1
func main() {
    engine := gin.Default()
    engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    userGroup := engine.Group("/user")
    userGroup.POST("/login", loginHandler)
    _ = engine.Run(":6912")
}

// @Summary 用户登录
// @Description 用户登录
// @Accept json
// @Produce json
// @Success 200 {string} string "success"
// @Router /login [post]
func loginHandler(context *gin.Context) {
    fullPath := "用户登录：" + context.FullPath()
    writeString, _ := context.Writer.WriteString(fullPath)
    fmt.Println(writeString)
}

 

==生成doc==

在程序的根路径下执行swag命令，生成接口文档

swag init -g .\gin\swagger\swagger01.go

 

命令执行成功之后，可以看到在根目录下生成了相关文件，

包括docs.go，swagger.json，swagger.yaml

 

==引入doc==

将docs目录引入到router所在的go文件中去。

 

==访问文档==

启动后台服务，然后通过浏览器打开swagger接口文档

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

 

页面截图：

 

==实际命令==

实际项目中的命令样例，其中service_api.go中定义了swagger的全局说明描述。

swag init -g .\gmqtt\plugin\service\service_api.go -o .\gmqtt\docs

 

--END--