接口文档 -- swagger

目录结构：

|—— swagger/   // 根目录
****|—— global/
********|—— vars.go  // 全局变量文件
****|—— go.mod  // go module 文件
****|—— main.go  // 入口文件

下载依赖：

# 下载 swag
go get github.com/swaggo/swag/cmd/swag
# 下载 swag--gin 插件
go get github.com/swaggo/gin-swagger
go get github.com/swaggo/files

编写代码：

1. 编写 swagger/go.mod 文件：
   module swaggerTest

2. 编写 swagger/main.go 文件：

    package main
   
    import (
        "fmt"
        "github.com/gin-gonic/gin"
        swaggerFiles "github.com/swaggo/files"
        ginSwagger "github.com/swaggo/gin-swagger"
        _ "swaggerTest/docs"
        "swaggerTest/global"
    )
   
    //    @title                        swagger测试接口文档
    //    @version                    1.0
    //    @description                swagger测试接口文档
    //    @termsofservice                http://www.test.com
    //    @contact.name                lee
    //    @contact.email                complet@163.com
    //    @securityDefinitions.apikey    ApiKeyAuth
    //    @in                            header
    //    @name                        Authorization
    func main() {
        router := gin.Default()
        router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
        router.GET("/get", routerGet)
        router.POST("/post", routerPost)
        router.POST("/json", routerJson)
        router.Run()
    }
   
    // 测试get请求
    //    @Summary        测试get请求
    //    @Description    测试get请求
    //    @Tags            测试get请求
    //    @Accept            text/plain
    //    @Produce        application/json
    //    @Param            name    query        string        true    "名称"
    //    @Success        200        {object}    global.Resp    "返回"
    //    @Router            /get [get]
    //    @Security        ApiKeyAuth
    func routerGet(c *gin.Context) {
        name := c.Query("name")
        resp := global.Resp{
            Message: fmt.Sprintf("hello %s!", name),
        }
        c.JSON(200, resp)
        return
    }
   
    // 测试post请求
    //    @Summary        测试post请求
    //    @Description    测试post请求
    //    @Tags            测试post请求
    //    @Accept            multipart/form-data
    //    @Produce        application/json
    //    @Param            name    formData    string        true    "名称"
    //    @Success        200        {object}    global.Resp    "返回"
    //    @Router            /post [post]
    //    @Security        ApiKeyAuth
    func routerPost(c *gin.Context) {
        name := c.PostForm("name")
        resp := global.Resp{
            Message: fmt.Sprintf("hello %s!", name),
        }
        c.JSON(200, resp)
        return
    }
   
    // 测试json请求
    //    @Summary        测试json请求
    //    @Description    测试json请求
    //    @Tags            测试json请求
    //    @Accept            application/json
    //    @Produce        application/json
    //    @Param            -    body        global.Req    true    "参数"
    //    @Success        200    {object}    global.Resp    "返回"
    //    @Router            /json [post]
    //    @Security        ApiKeyAuth
    func routerJson(c *gin.Context) {
        var params global.Req
        if err := c.Bind(&params); err != nil {
            c.JSON(200, map[string]interface{}{
                "message": err.Error(),
            })
            return
        }
        resp := global.Resp{
            Message: fmt.Sprintf("hello %s!", params.Name),
        }
        c.JSON(200, resp)
        return
    }

3. 编写 swagger/global/vars.go 文件：

    package global
   
    type Req struct {
        Name string `json:"name"`
    }
   
    type Resp struct {
        Message string `json:"message"`
    }

下载包：

cd swagger
go mod tidy

生成 swagger 静态目录：

cd swagger
swag init

格式化 swagger 注释：

cd swagger
swag fmt

启动代码：

cd swagger
go run main.go

访问 swagger 文档：
http://localhost:8080/swagger/index.html