go使用swagger生成接口文档

1. 安装swag 工具
   go get -u github.com/swaggo/swag/cmd/swag
2. 在入口文件写上项目的简介

package main

import (
    "flag"
    "open-api/internal/app/fund"
)

// @title 这里写标题`
// @version 1.0`
// @description 这里写描述信息`
// @termsOfService [http://swagger.io/terms/](http://swagger.io/terms/)`
// @contact.name 这里写联系人信息`
// @contact.url [http://www.swagger.io/support](http://www.swagger.io/support)`
// @contact.email [email protected]`
// @license.name Apache 2.0`
// @license.url [http://www.apache.org/licenses/LICENSE-2.0.html](http://www.apache.org/licenses/LICENSE-2.0.html)`
// @host 这里写接口服务的host`
// @BasePath 这里写base path`

func main() {
    var configPath string
    flag.StringVar(&configPath, "config", "./configs", "config path")
    flag.Parse()
    fund.Run(configPath)
}

3. 在你代码中处理请求的接口函数（通常位于controller层）按如下方式写上注释：

// @Summary 支付列表
// @Description 获取支付列表
// @Accept  json
// @Produce  json
// @param Authorization header string true "验证参数Bearer和token空格拼接"
// @Param  body body st.PaySearch true "交款查询参数"
// @Success 200 {object} response.Response{data=st.PayListResponse}
// @Failure 500 {object} response.Response
// @Router /app/pay/list [post]
func PayList(ctx *gin.Context) {
    var (
        paySearch st.PaySearch
        data      []st.PayListResponse
        err       error
    )
    if err := ctx.Bind(&paySearch); err != nil {
        response.Failed(ctx, response.InvalidParams, response.GetMsg(response.InvalidParams), data, err)
        return
    }
    data, err = logic.GetPayListNew(p)

    if err != nil {
        response.Failed(ctx, response.Error, response.GetMsg(response.Error), data, err)
        return
    }
    response.Successed(ctx, response.Success, response.GetMsg(response.Success), data)
}

4. 上面注释中参数类型使用了object，st.PaySearch st.PayListResponse response.Response具体定义如下：

type Response struct {
    Code int         `json:"code"`
    Msg  string      `json:"msg"`
    Data interface{} `json:"data"`
}

type PayListResponse struct {
    HouseBase
    Id                 int             `json:"id"`
    Name               string          `json:"name"`
    PayAmount          decimal.Decimal `json:"pay_amount"`
    PayArea            decimal.Decimal `json:"pay_area"`
    BankAccountingTime TimeShowDay     `json:"bank_accounting_time"`
    BankName           string          `json:"bank_name"`
    AccountCode        string          `json:"account_code"`
    BankCode           string          `json:"bank_code"`
}

type PaySearch struct {
    Phone  string `form:"phone" binding:"required,phoneValid"`
    Status string `form:"status" binding:"required,oneof='0' '1'"`
}

5. 生成文档

swag init -g cmd/main.go  // -g 指定main.go 的位置，  我这边是在cmd文件中
此时目录中多了docs
./docs
├── docs.go
├── swagger.json
└── swagger.yaml

image.png

6. 引入gin-swagger渲染文档数据, 利用条件编译来决定是否编译swagger，因为线上运行时，不需要swagger

image.png

doc_swag.go

// +build doc

package router

import (
    swaggerFiles "github.com/swaggo/files"
    ginSwagger "github.com/swaggo/gin-swagger"
)

func init() {
    swagHandler = ginSwagger.WrapHandler(swaggerFiles.Handler)
}

swag.go 目前是空的

router.go

package router

import (
    _ "open-api/docs"
    "open-api/internal/app/fund/controller"
    "open-api/internal/app/fund/middleware"
    validator2 "open-api/pkg/validator"

    "github.com/gin-gonic/gin/binding"
    "github.com/go-playground/validator/v10"

    "github.com/gin-gonic/gin"
)

var swagHandler gin.HandlerFunc

func InitRouter() *gin.Engine {
    r := gin.New()
    r.Use(gin.Logger())
    r.Use(gin.Recovery())
    r.Use(middleware.Cors())

    // 开启swag
    if swagHandler != nil {
        r.GET("/swagger/*any", swagHandler)
    }

    if v, ok := binding.Validator.Engine().(*validator.Validate); ok {
        _ = v.RegisterValidation("phoneValid", validator2.PhoneValidHook)
    }
    return r
}

7. 在goland中配置build参数，以便本地调试

image.png

至此就完成了。 如有问题请私信我。